Obravnava napak
Zahtevek, ki ne uspe, vrne statusno kodo HTTP in telo JSON s tipom napake in sporočilom. Ta stran navaja vsak status, prikazuje telo napake vsakega formata API-ja in pove, katere napake je vredno poslati znova.
SDK-ji sprožijo objekt napake, ki nosi statusno kodo in polja telesa. Ta zahtevek navaja model, ki ne obstaja:
import openai
from openai import OpenAI
client = OpenAI(
api_key="YOUR_API_KEY",
base_url="https://api.shannon-ai.com/v1",
)
try:
client.chat.completions.create(
model="no-such-model",
messages=[{"role": "user", "content": "Hello"}],
)
except openai.APIStatusError as error:
print(error.status_code) # 400
print(error.type) # invalid_request_error
print(error.body["message"]) # unknown model: no-such-model
print(error.response.headers.get("x-request-id")) # the id of this request import OpenAI from "openai";
const client = new OpenAI({
apiKey: "YOUR_API_KEY",
baseURL: "https://api.shannon-ai.com/v1",
});
try {
await client.chat.completions.create({
model: "no-such-model",
messages: [{ role: "user", content: "Hello" }],
});
} catch (error) {
if (!(error instanceof OpenAI.APIError)) throw error;
console.log(error.status); // 400
console.log(error.type); // invalid_request_error
console.log(error.error.message); // unknown model: no-such-model
} curl -i https://api.shannon-ai.com/v1/chat/completions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "no-such-model",
"messages": [{"role": "user", "content": "Hello"}]
}' Vrne status 400 in to telo:
{
"error": {
"type": "invalid_request_error",
"message": "unknown model: no-such-model"
}
} Telo napake
Obstajata dve telesi. /v1/messages odgovarja v formatu Anthropic; vsak drug endpoint odgovarja v formatu OpenAI. V obeh so podrobnosti v error.type in error.message, zato en bralnik služi vsem endpointom.
{
"error": {
"type": "authentication_error",
"message": "Invalid API key",
"code": "invalid_api_key",
"param": null
}
} {
"type": "error",
"error": {
"type": "authentication_error",
"message": "Invalid API key"
}
} | Polje | Tip | Opis |
|---|---|---|
error.type | string | Vrsta napake. Glejte spodaj Tipi napak. |
error.message | string | Stavek za človeka. Besedila v spodnjih tabelah so stalna, razen spremenljivih delov, prikazanih kot <id>, <n> ali …. |
error.code | string | null | Prisotno pri nekaterih napakah formata OpenAI: invalid_api_key s 401, request_too_large s 413, context_length_exceeded, kadar je pogovor predolg, sicer null ali odsotno. Najprej se odločite po statusu in error.type, code pa obravnavajte kot dodatek. |
error.param | null | Prisotno pri istih napakah kot code. Vedno null. |
type | string | Samo format Anthropic. Vedno error. |
Tipi napak
| Vrsta | Statusi | Opis |
|---|---|---|
invalid_request_error | 400, 413, 415, 422 | Zahtevek sam je napačen: polje, telo, id modela ali vhod, ki ga model ne sprejme. Zahtevek spremenite, preden ga pošljete znova. |
authentication_error | 401 | API ključ manjka, je neznan ali preklican. |
not_found_error | 404 | Pot ne obstaja. |
rate_limit_error | 429 | Stanje ne pokrije zahtevka, zaščita pred poplavo zahtevkov ga je ustavila ali pa je model zaseden. Sporočilo pove, kaj od tega. |
api_error | 500, 502, 503, 504 | Zahtevek je bil v redu, napaka je na naši strani. Pošljite ga znova. |
server_error | 500 | Zahtevek je bil v redu, napaka je na naši strani. Pošljite ga znova. |
Statusne kode
| Stanje | Vrsta | Sporočilo | Kdaj |
|---|---|---|---|
400 | invalid_request_error | Failed to parse the request body as JSON: … | Telo ni veljaven JSON. |
400 | invalid_request_error | unknown model: <id> | model ni objavljen id. Na /v1/responses tudi, kadar model manjka. |
400 | invalid_request_error | No user message provided | Ravni Shannon: zahtevek ne vsebuje besedila uporabnika. |
400 | invalid_request_error | <id> does not accept image input | Slika je bila poslana gostovanemu modelu z odprtimi utežmi brez vhoda s slikami. |
400 | invalid_request_error | audio and video input are not supported by any hosted model | Zvočni ali video del je bil poslan gostovanemu modelu z odprtimi utežmi. |
400 | invalid_request_error | <id> does not accept response_format | Strukturiran izhod je bil zahtevan od gostovanega modela z odprtimi utežmi, ki ga nima. |
400 | invalid_request_error | <id> does not accept response_format json_schema; use json_object | Shema JSON je bila poslana gostovanemu modelu z odprtimi utežmi, ki sprejme samo json_object. |
400 | invalid_request_error | unknown reasoning effort '<value>'; expected off, low, medium or high | Napor razmišljanja ni ena od navedenih vrednosti. Gostovani modeli z odprtimi utežmi. |
400 | invalid_request_error | count_tokens is available for the hosted open models; unknown model: <id> | Štetje tokenov je bilo zahtevano za model zunaj gostovanih modelov z odprtimi utežmi. |
401 | authentication_error | Missing authentication | API ključ ni bil poslan. |
401 | authentication_error | Invalid API key | Ključ je neznan, nadomeščen z novejšim ali preklican. |
404 | not_found_error | Not Found | Pot ne obstaja, na primer /v1/embeddings. |
405 | api_error | Method Not Allowed | Pot obstaja, vendar ne s to metodo HTTP. |
413 | invalid_request_error | Failed to buffer the request body: … | Telo zahtevka je večje od 32 MiB. |
415 | invalid_request_error | Expected request with `Content-Type: application/json` | Glava Content-Type manjka ali ni application/json. |
422 | invalid_request_error | Failed to deserialize the JSON body into the target type: … | Obvezno polje manjka, na primer messages, ali pa ima polje napačen tip JSON. |
429 | rate_limit_error | Quota exceeded. Upgrade your plan at shannon-ai.com/plan | Omejitev izhoda zahtevka je večja od tega, kar je ostalo na vašem stanju. |
429 | rate_limit_error | Too many requests. Retry in <n>s. | Zaščita pred poplavo zahtevkov: več kot 120 zahtevkov v eni minuti na vašem računu. <n> je število sekund do konca minute. |
429 | rate_limit_error | Shannon Coder call quota reached. Upgrade your plan at shannon-ai.com/plan | shannon-coder-1 na /v1/chat/completions in /v1/messages: klici Shannon Coder vašega paketa za trenutno 4-urno okno so porabljeni. |
429 | rate_limit_error | Shannon routes are temporarily busy. Please retry. | Model je trenutno zaseden. |
500 | server_error | The model backend failed to answer. Please retry. | Model ni ustvaril odgovora. |
500 | server_error | An internal error occurred. Please retry. | Notranja napaka med pripravo zahtevka. |
502 | api_error | The model backend failed to answer. Please retry. | Model ni ustvaril odgovora. Družina Shannon 3 in gostovani modeli z odprtimi utežmi. |
503 | api_error | Could not verify your quota right now. Please retry. | Vašega stanja trenutno ni bilo mogoče prebrati. |
503 | api_error | token counting is temporarily unavailable for this model | Štetje tokenov za ta model trenutno ni na voljo. |
504 | api_error | upstream timed out | Gostovani model z odprtimi utežmi je potreboval dlje od časovne omejitve zahtevka, ki ni pretočen. |
Preverjanja potekajo v tem vrstnem redu: API ključ, telo zahtevka, id modela, zaščita pred poplavo zahtevkov, stanje. Zahtevek z napačnim ključem in napačnim telesom zato vrne 401. Zahtevek, zavrnjen s statusom 4xx, se ne obračuna.
Stanje in zaščita pred poplavo zahtevkov
Vsak zahtevek se streže enako: ni stopenj hitrosti in ni ločene kvote API. Na 429 lahko vseeno odgovorita dve stvari, obe s tipom rate_limit_error. Sporočilo ju loči.
Stanje
Vaše stanje je današnja dnevna kvota paketa, ki se ponastavi ob 00:00 UTC, in za njo vaš kupljeni kredit. Klepet in API črpata iz istega stanja.
Vsak zahtevek najprej odloži svojo omejitev izhoda: max_tokens ali max_output_tokens na /v1/responses, 4,096, če ne pošljete nobenega. Ko je odgovor končan, odloženi znesek nadomesti to, kar je zahtevek porabil. Če se znesek ne prilega preostalemu stanju, zahtevek vrne Quota exceeded, preden se model zažene.
Zahtevki, ki tečejo hkrati, vsak odloži svoj znesek. Veliko vzporednih zahtevkov z visokim max_tokens zato lahko za trenutek porabi stanje, tudi če je vsak odgovor kratek. Nižji max_tokens odloži manj.
Zaščita pred poplavo zahtevkov
Zaščita pred poplavo zahtevkov dovoljuje 120 zahtevkov na minuto na račun. Šteje račun, ne ključa, na /v1/chat/completions, /v1/responses in /v1/messages skupaj. Minuta se začne z vašim prvim zahtevkom.
Zahtevek številka 121 znotraj te minute vrne Too many requests. Retry in <n>s. in ne stane nič. Šteje tudi zavrnjene zahtevke, zato odjemalec, ki pošilja znova brez čakanja, ostane zavrnjen, dokler minuta ne mine. Počakajte <n> sekund iz sporočila.
Vzporedno poslani zahtevki niso zavrnjeni zaradi vzporednosti. Čakajo v vrsti in dobijo odgovor po vrsti.
GET /v1/models in endpointi za štetje tokenov se ne štejejo.
Več o omejitvah in stanju ter kje vidite lastno stanje in porabo: Omejitve in stanje Ključi in poraba
Kaj ponoviti
Zahtevek pošljite znova samo, kadar lahko isti zahtevek uspe. SDK-ja OpenAI in Anthropic že sama dvakrat ponovita odgovore 429 in 5xx; to spremenite z max_retries (maxRetries v JavaScriptu).
| Napaka | Ponovno poslati? | Kako |
|---|---|---|
400, 404, 405, 413, 415, 422 | Ne. Najprej popravite zahtevek. | Sporočilo navaja polje, model ali vhod, ki je napačen. |
401 | Ne. Uporabite veljaven ključ. | Ključ ustvarite ali zamenjajte na strani Ključi in poraba. |
429 Too many requests | Da, po čakanju. | Počakajte število sekund iz sporočila, nato pošljite isti zahtevek. |
429 Quota exceeded | Ne v tej obliki. | Znižajte max_tokens, počakajte na dnevno ponastavitev ob 00:00 UTC ali dodajte kredit. |
429 Shannon Coder call quota reached | Da, v naslednjem oknu. | Okna se začnejo vsake 4 ure od 00:00 UTC. Drug model odgovori takoj. |
429 … temporarily busy | Da. | Počakajte nekaj sekund, nato pri vsakem nadaljnjem poskusu dlje. |
500, 502, 503 | Da. | Počakajte 1 sekundo, nato 2, 4 in 8. Po nekaj poskusih nehajte in sporočite id zahtevka. |
504 | Da. | Pošljite ga z stream nastavljenim na true: časovna omejitev velja za odgovore, ki niso pretočni. |
Zanka ponavljanja, ki sledi tej tabeli:
import re
import time
import openai
from openai import OpenAI
# max_retries=0: this loop does the retrying, the SDK does not add its own.
client = OpenAI(api_key="YOUR_API_KEY", base_url="https://api.shannon-ai.com/v1", max_retries=0)
def create_with_retry(attempts=5, **request):
for attempt in range(attempts):
try:
return client.chat.completions.create(**request)
except openai.RateLimitError as error:
text = str(error)
flood = re.search(r"Retry in (\d+)s", text)
if flood:
time.sleep(int(flood.group(1))) # flood protection: wait out the minute
elif "temporarily busy" in text:
time.sleep(2 ** attempt)
else:
raise # balance: a wait of seconds does not help
except (openai.InternalServerError, openai.APIConnectionError):
time.sleep(2 ** attempt) # 1, 2, 4, 8 seconds
raise RuntimeError("the request failed after all attempts")
response = create_with_retry(
model="shannon-3",
messages=[{"role": "user", "content": "Hello"}],
)
print(response.choices[0].message.content) import OpenAI from "openai";
// maxRetries: 0 — this loop does the retrying, the SDK does not add its own.
const client = new OpenAI({ apiKey: "YOUR_API_KEY", baseURL: "https://api.shannon-ai.com/v1", maxRetries: 0 });
const sleep = (seconds) => new Promise((resolve) => setTimeout(resolve, seconds * 1000));
async function createWithRetry(request, attempts = 5) {
for (let attempt = 0; attempt < attempts; attempt++) {
try {
return await client.chat.completions.create(request);
} catch (error) {
const text = String(error.message);
const flood = text.match(/Retry in (\d+)s/);
if (error.status === 429 && flood) {
await sleep(Number(flood[1])); // flood protection: wait out the minute
} else if (error.status === 429 && text.includes("temporarily busy")) {
await sleep(2 ** attempt);
} else if (error.status >= 500 || error instanceof OpenAI.APIConnectionError) {
await sleep(2 ** attempt); // 1, 2, 4, 8 seconds
} else {
throw error; // wrong request, wrong key or balance
}
}
}
throw new Error("the request failed after all attempts");
}
const response = await createWithRetry({
model: "shannon-3",
messages: [{ role: "user", content: "Hello" }],
});
console.log(response.choices[0].message.content); Napake znotraj toka
Tok ima status 200 od prvega bajta. Napaka po tem prispe kot dogodek znotraj toka: kos s članom error na /v1/chat/completions, dogodek error na /v1/messages, dogodek response.failed ali error na /v1/responses. Sklepni dogodki toka še vedno sledijo. Tak odgovor obravnavajte kot neuspel in zahtevek pošljite znova, kot pri statusu 5xx.
Pogovor, ki je daljši od kontekstnega okna modela, se sporoči na ta način, s tipom invalid_request_error in kodo context_length_exceeded. Pogovor skrajšajte, preden ga pošljete znova.
Natančni okviri so opisani pri pretakanju. Pretakanje
Idi zahtevkov
Vsak odgovor, tudi napake, ima glavo x-request-id. To je vrednost, ki ste jo poslali v svoji glavi x-request-id, ali 12 šestnajstiških znakov, če je niste poslali. Zapišite jo v dnevnik in jo navedite, ko prosite za pomoč pri zahtevku.