Spracovanie chýb
Request, ktorý zlyhá, vráti stavový kód HTTP a telo JSON s typom chyby a správou. Táto stránka uvádza každý stav, ukazuje telo chyby každého formátu API a hovorí, ktoré chyby sa oplatí posielať znova.
SDK vyvolajú objekt chyby, ktorý nesie stavový kód a polia tela. Tento request uvádza model, ktorý neexistuje:
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"}]
}' Vráti stav 400 a toto telo:
{
"error": {
"type": "invalid_request_error",
"message": "unknown model: no-such-model"
}
} Telo chyby
Existujú dve telá. /v1/messages odpovedá vo formáte Anthropic; každý ďalší endpoint odpovedá vo formáte OpenAI. V oboch sú podrobnosti v error.type a error.message, takže jeden čítač obslúži všetky endpointy.
{
"error": {
"type": "authentication_error",
"message": "Invalid API key",
"code": "invalid_api_key",
"param": null
}
} {
"type": "error",
"error": {
"type": "authentication_error",
"message": "Invalid API key"
}
} | Pole | Typ | Popis |
|---|---|---|
error.type | string | Druh chyby. Pozrite Typy chýb nižšie. |
error.message | string | Veta pre človeka. Texty v tabuľkách nižšie sú stabilné až na premenné časti, uvedené ako <id>, <n> alebo …. |
error.code | string | null | Prítomný pri niektorých chybách formátu OpenAI: invalid_api_key so 401, request_too_large so 413, context_length_exceeded, keď je konverzácia príliš dlhá, inak null alebo chýba. Najprv sa rozhodujte podľa stavu a error.type a code berte ako doplnok. |
error.param | null | Prítomný pri rovnakých chybách ako code. Vždy null. |
type | string | Iba formát Anthropic. Vždy error. |
Typy chýb
| Typ | Stavy | Popis |
|---|---|---|
invalid_request_error | 400, 413, 415, 422 | Samotný request je nesprávny: pole, telo, id modelu alebo vstup, ktorý model neberie. Pred ďalším odoslaním request zmeňte. |
authentication_error | 401 | API kľúč chýba, je neznámy alebo zrušený. |
not_found_error | 404 | Cesta neexistuje. |
rate_limit_error | 429 | Zostatok nepokrýva request, zastavila ho ochrana pred zahltením alebo je model zaneprázdnený. Správa hovorí, ktorý prípad nastal. |
api_error | 500, 502, 503, 504 | Request bol v poriadku a zlyhanie je na našej strane. Pošlite ho znova. |
server_error | 500 | Request bol v poriadku a zlyhanie je na našej strane. Pošlite ho znova. |
Stavové kódy
| Stav | Typ | Správa | Kedy |
|---|---|---|---|
400 | invalid_request_error | Failed to parse the request body as JSON: … | Telo nie je platný JSON. |
400 | invalid_request_error | unknown model: <id> | model nie je zverejnené id. Na /v1/responses aj vtedy, keď model chýba. |
400 | invalid_request_error | No user message provided | Úrovne Shannon: request neobsahuje žiadny text používateľa. |
400 | invalid_request_error | <id> does not accept image input | Obrázok bol odoslaný hostovanému open-weight modelu bez obrázkového vstupu. |
400 | invalid_request_error | audio and video input are not supported by any hosted model | Časť s audiom alebo videom bola odoslaná hostovanému open-weight modelu. |
400 | invalid_request_error | <id> does not accept response_format | Štruktúrovaný výstup sa žiadal od hostovaného open-weight modelu, ktorý ho nemá. |
400 | invalid_request_error | <id> does not accept response_format json_schema; use json_object | Schéma JSON bola odoslaná hostovanému open-weight modelu, ktorý berie iba json_object. |
400 | invalid_request_error | unknown reasoning effort '<value>'; expected off, low, medium or high | Úsilie pri uvažovaní nie je jednou z uvedených hodnôt. Hostované open-weight modely. |
400 | invalid_request_error | count_tokens is available for the hosted open models; unknown model: <id> | Počítanie tokenov sa žiadalo pre model mimo hostovaných open-weight modelov. |
401 | authentication_error | Missing authentication | Nebol odoslaný žiadny API kľúč. |
401 | authentication_error | Invalid API key | Kľúč je neznámy, nahradil ho novší alebo bola zrušená jeho platnosť. |
404 | not_found_error | Not Found | Cesta neexistuje, napríklad /v1/embeddings. |
405 | api_error | Method Not Allowed | Cesta existuje, ale nie s touto metódou HTTP. |
413 | invalid_request_error | Failed to buffer the request body: … | Telo requestu je väčšie než 32 MiB. |
415 | invalid_request_error | Expected request with `Content-Type: application/json` | Hlavička Content-Type chýba alebo nie je application/json. |
422 | invalid_request_error | Failed to deserialize the JSON body into the target type: … | Chýba povinné pole, napríklad messages, alebo pole má nesprávny typ JSON. |
429 | rate_limit_error | Quota exceeded. Upgrade your plan at shannon-ai.com/plan | Limit výstupu requestu je väčší, než koľko zostáva z vášho zostatku. |
429 | rate_limit_error | Too many requests. Retry in <n>s. | Ochrana pred zahltením: viac ako 120 requestov za minútu na vašom účte. <n> je počet sekúnd do konca minúty. |
429 | rate_limit_error | Shannon Coder call quota reached. Upgrade your plan at shannon-ai.com/plan | shannon-coder-1 na /v1/chat/completions a /v1/messages: volania Shannon Coder vášho plánu pre aktuálne 4-hodinové okno sú vyčerpané. |
429 | rate_limit_error | Shannon routes are temporarily busy. Please retry. | Model je v tejto chvíli zaneprázdnený. |
500 | server_error | The model backend failed to answer. Please retry. | Model nevytvoril odpoveď. |
500 | server_error | An internal error occurred. Please retry. | Vnútorné zlyhanie počas prípravy requestu. |
502 | api_error | The model backend failed to answer. Please retry. | Model nevytvoril odpoveď. Rodina Shannon 3 a hostované open-weight modely. |
503 | api_error | Could not verify your quota right now. Please retry. | Váš zostatok sa v tejto chvíli nepodarilo prečítať. |
503 | api_error | token counting is temporarily unavailable for this model | Počítanie tokenov nie je pre tento model v tejto chvíli dostupné. |
504 | api_error | upstream timed out | Hostovaný open-weight model potreboval viac času než je časový limit requestu, ktorý sa nestreamuje. |
Kontroly bežia v tomto poradí: API kľúč, telo requestu, id modelu, ochrana pred zahltením, zostatok. Request so zlým kľúčom a zlým telom preto vráti 401. Request odmietnutý so stavom 4xx sa neúčtuje.
Zostatok a ochrana pred zahltením
Každý request sa obsluhuje rovnako: neexistujú cenové úrovne rýchlosti ani osobitná kvóta API. Na 429 však môžu odpovedať dve veci, obe s typom rate_limit_error. Rozlíši ich správa.
Zostatok
Váš zostatok je dnešný limit plánu, ktorý sa obnovuje o 00:00 UTC, a po ňom váš zakúpený kredit. Chat a API čerpajú z rovnakého zostatku.
Každý request najprv vyhradí svoj limit výstupu: max_tokens, alebo max_output_tokens na /v1/responses, 4,096, keď neposielate ani jedno. Po dokončení odpovede sa vyhradená suma nahradí tým, čo request použil. Ak sa suma nezmestí do zostávajúceho zostatku, request vráti Quota exceeded ešte pred spustením modelu.
Requesty bežiace súčasne si každý vyhradzujú vlastnú sumu. Veľa paralelných requestov s vysokým max_tokens tak môže na chvíľu vyčerpať zostatok, aj keď je každá odpoveď krátka. Nižšie max_tokens vyhradí menej.
Ochrana pred zahltením
Ochrana pred zahltením povoľuje 120 requestov za minútu na účet. Počíta účet, nie kľúč, naprieč /v1/chat/completions, /v1/responses a /v1/messages spolu. Minúta začína vaším prvým requestom.
Request číslo 121 v tejto minúte vráti Too many requests. Retry in <n>s. a nič nestojí. Odmietnuté requesty sa počítajú tiež, takže klient, ktorý posiela znova bez čakania, zostáva odmietaný, kým minúta neskončí. Počkajte <n> sekúnd zo správy.
Requesty poslané paralelne sa neodmietajú kvôli paralelnosti. Čakajú v rade a odpovedá sa im postupne.
GET /v1/models a endpointy na počítanie tokenov sa nepočítajú.
Viac o limitoch a zostatku a kde vidíte vlastný zostatok a využitie: Limity a zostatok Kľúče a využitie
Čo opakovať
Request posielajte znova iba vtedy, keď môže ten istý request uspieť. SDK od OpenAI a Anthropic už odpovede 429 a 5xx samy opakujú dvakrát; zmeníte to cez max_retries (maxRetries v JavaScripte).
| Chyba | Poslať znova? | Ako |
|---|---|---|
400, 404, 405, 413, 415, 422 | Nie. Najprv request opravte. | Správa uvádza pole, model alebo vstup, ktorý je nesprávny. |
401 | Nie. Použite platný kľúč. | Kľúč vytvorte alebo vymeňte na stránke Kľúče a využitie. |
429 Too many requests | Áno, po čakaní. | Počkajte počet sekúnd zo správy a potom pošlite ten istý request. |
429 Quota exceeded | Nie v tomto stave. | Znížte max_tokens, počkajte na denné obnovenie o 00:00 UTC alebo pridajte kredit. |
429 Shannon Coder call quota reached | Áno, v ďalšom okne. | Okná začínajú každé 4 hodiny od 00:00 UTC. Iný model odpovie okamžite. |
429 … temporarily busy | Áno. | Počkajte niekoľko sekúnd, pri každom ďalšom pokuse dlhšie. |
500, 502, 503 | Áno. | Počkajte 1 sekundu, potom 2, 4 a 8. Po niekoľkých pokusoch skončite a nahláste id requestu. |
504 | Áno. | Pošlite ho s stream nastaveným na true: časový limit platí pre odpovede, ktoré sa nestreamujú. |
Slučka opakovania podľa tejto tabuľky:
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); Chyby vnútri streamu
Stream má stav 200 od prvého bajtu. Zlyhanie po ňom príde ako udalosť vnútri streamu: chunk s členom error na /v1/chat/completions, udalosť error na /v1/messages, udalosť response.failed alebo error na /v1/responses. Záverečné udalosti streamu stále nasledujú. Takúto odpoveď považujte za zlyhanú a pošlite request znova, ako pri stave 5xx.
Takto sa hlási konverzácia dlhšia než kontextové okno modelu, s typom invalid_request_error a kódom context_length_exceeded. Pred ďalším odoslaním konverzáciu skráťte.
Presné frame sú popísané pri streamovaní. Streamovanie
Id requestov
Každá odpoveď, vrátane chýb, má hlavičku x-request-id. Je to hodnota, ktorú ste poslali vo vlastnej hlavičke x-request-id, alebo 12 hexadecimálnych znakov, ak ste neposlali žiadnu. Zaznamenajte ju a uveďte ju, keď žiadate o pomoc s requestom.