Hibakezelés
A sikertelen kérés HTTP státuszkódot és egy JSON-törzset ad vissza hibatípussal és üzenettel. Ez az oldal felsorol minden státuszt, megmutatja az egyes API-formátumok hibatörzsét, és megmondja, mely hibák érdemelnek újraküldést.
Az SDK-k hibaobjektumot dobnak, amely a státuszkódot és a törzs mezőit hordozza. Ez a kérés egy nem létező modellt nevez meg:
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"}]
}' 400 státuszt és ezt a törzset adja vissza:
{
"error": {
"type": "invalid_request_error",
"message": "unknown model: no-such-model"
}
} Hibatörzs
Két törzs létezik. A /v1/messages Anthropic formátumban válaszol; minden más végpont OpenAI formátumban. Mindkettőben a részletek az error.type és error.message mezőben vannak, így egyetlen olvasó kiszolgálja az összes végpontot.
{
"error": {
"type": "authentication_error",
"message": "Invalid API key",
"code": "invalid_api_key",
"param": null
}
} {
"type": "error",
"error": {
"type": "authentication_error",
"message": "Invalid API key"
}
} | Mező | Típus | Leírás |
|---|---|---|
error.type | string | A hiba fajtája. Lásd lent a Hibatípusok részt. |
error.message | string | Egy ember számára írt mondat. Az alábbi táblázatok szövegei a változó részeiktől eltekintve állandók; ezeket <id>, <n> vagy … jelzi. |
error.code | string | null | Az OpenAI formátum egyes hibáinál van jelen: invalid_api_key 401 esetén, request_too_large 413 esetén, context_length_exceeded, ha a beszélgetés túl hosszú, egyébként null vagy hiányzik. Először a státuszról és az error.type mezőről döntsd el, a code csak többlet. |
error.param | null | Ugyanazokon a hibákon van jelen, mint a code. Mindig null. |
type | string | Csak az Anthropic formátumban. Mindig error. |
Hibatípusok
| Típus | Státuszok | Leírás |
|---|---|---|
invalid_request_error | 400, 413, 415, 422 | Maga a kérés hibás: egy mező, a törzs, a modellazonosító vagy olyan bemenet, amelyet a modell nem fogad. Változtasd meg a kérést, mielőtt újra elküldöd. |
authentication_error | 401 | Az API-kulcs hiányzik, ismeretlen vagy vissza van vonva. |
not_found_error | 404 | Az útvonal nem létezik. |
rate_limit_error | 429 | Az egyenleg nem fedezi a kérést, a flood protection leállította, vagy a modell foglalt. Az üzenet megmondja, melyik. |
api_error | 500, 502, 503, 504 | A kérés rendben volt, a hiba nálunk van. Küldd el újra. |
server_error | 500 | A kérés rendben volt, a hiba nálunk van. Küldd el újra. |
Státuszkódok
| Státusz | Típus | Üzenet | Mikor |
|---|---|---|---|
400 | invalid_request_error | Failed to parse the request body as JSON: … | A törzs nem érvényes JSON. |
400 | invalid_request_error | unknown model: <id> | A model nem közzétett azonosító. A /v1/responses végponton akkor is, ha a model hiányzik. |
400 | invalid_request_error | No user message provided | Shannon szintek: a kérés nem tartalmaz felhasználói szöveget. |
400 | invalid_request_error | <id> does not accept image input | Képet küldtek egy olyan hosztolt nyílt súlyú modellnek, amely nem támogat képbemenetet. |
400 | invalid_request_error | audio and video input are not supported by any hosted model | Hang- vagy videórészt küldtek egy hosztolt nyílt súlyú modellnek. |
400 | invalid_request_error | <id> does not accept response_format | Strukturált kimenetet kértek egy olyan hosztolt nyílt súlyú modelltől, amely nem támogatja. |
400 | invalid_request_error | <id> does not accept response_format json_schema; use json_object | JSON-sémát küldtek egy olyan hosztolt nyílt súlyú modellnek, amely csak json_object módot fogad. |
400 | invalid_request_error | unknown reasoning effort '<value>'; expected off, low, medium or high | A reasoning effort nem szerepel a felsorolt értékek között. Hosztolt nyílt súlyú modellek. |
400 | invalid_request_error | count_tokens is available for the hosted open models; unknown model: <id> | Tokenszámlálást kértek a hosztolt nyílt súlyú modelleken kívüli modellhez. |
401 | authentication_error | Missing authentication | Nem küldtek API-kulcsot. |
401 | authentication_error | Invalid API key | A kulcs ismeretlen, újabb váltotta le, vagy vissza lett vonva. |
404 | not_found_error | Not Found | Az útvonal nem létezik, például /v1/embeddings. |
405 | api_error | Method Not Allowed | Az útvonal létezik, de ezzel a HTTP-metódussal nem. |
413 | invalid_request_error | Failed to buffer the request body: … | A kérés törzse nagyobb 32 MiB-nál. |
415 | invalid_request_error | Expected request with `Content-Type: application/json` | A Content-Type fejléc hiányzik, vagy nem application/json. |
422 | invalid_request_error | Failed to deserialize the JSON body into the target type: … | Egy kötelező mező hiányzik, például a messages, vagy egy mező JSON-típusa hibás. |
429 | rate_limit_error | Quota exceeded. Upgrade your plan at shannon-ai.com/plan | A kérés kimeneti korlátja nagyobb, mint az egyenlegedből megmaradt rész. |
429 | rate_limit_error | Too many requests. Retry in <n>s. | Flood protection: egy percen belül több mint 120 kérés érkezett a fiókodról. Az <n> a perc végéig hátralévő másodpercek száma. |
429 | rate_limit_error | Shannon Coder call quota reached. Upgrade your plan at shannon-ai.com/plan | shannon-coder-1 a /v1/chat/completions és /v1/messages végponton: a csomagod Shannon Coder hívásai elfogytak az aktuális 4 órás ablakra. |
429 | rate_limit_error | Shannon routes are temporarily busy. Please retry. | A modell ebben a pillanatban foglalt. |
500 | server_error | The model backend failed to answer. Please retry. | A modell nem adott választ. |
500 | server_error | An internal error occurred. Please retry. | Belső hiba a kérés előkészítése közben. |
502 | api_error | The model backend failed to answer. Please retry. | A modell nem adott választ. Shannon 3 család és hosztolt nyílt súlyú modellek. |
503 | api_error | Could not verify your quota right now. Please retry. | Az egyenleged ebben a pillanatban nem olvasható. |
503 | api_error | token counting is temporarily unavailable for this model | A tokenszámlálás ebben a pillanatban nem érhető el ennél a modellnél. |
504 | api_error | upstream timed out | Egy hosztolt nyílt súlyú modell tovább tartott a nem streamelt kérés időkorlátjánál. |
Az ellenőrzések ebben a sorrendben futnak: API-kulcs, kérés törzse, modellazonosító, flood protection, egyenleg. A hibás kulcsú és hibás törzsű kérés ezért 401-et kap. A 4xx státusszal elutasított kérést nem számlázzák.
Egyenleg és flood protection
Minden kérést egyformán szolgál ki a rendszer: nincsenek sebességszintek és külön API-kvóta. Két dolog mégis válaszolhat 429 kóddal, mindkettő rate_limit_error típussal. Az üzenet különbözteti meg őket.
Egyenleg
Az egyenleged a mai csomagkeret, amely 00:00 UTC-kor újraindul, utána a vásárolt kredit. A chat és az API ugyanabból az egyenlegből fogyaszt.
Minden kérés először lefoglalja a kimeneti korlátját: a max_tokens értéket, a /v1/responses végponton a max_output_tokens értéket, 4,096-ot, ha egyiket sem küldöd. Ha a válasz kész, a lefoglalt mennyiséget a kérés tényleges használata váltja fel. Ha a mennyiség nem fér bele a megmaradt egyenlegbe, a kérés Quota exceeded hibát ad, még a modell indulása előtt.
Az egyidejűleg futó kérések mind lefoglalják a saját mennyiségüket. Sok, magas max_tokens értékű párhuzamos kérés ezért egy pillanatra kimerítheti az egyenleget, még ha mindegyik válasz rövid is. Alacsonyabb max_tokens kevesebbet foglal le.
Flood protection
A flood protection fiókonként percenként 120 kérést enged. A fiókot számolja, nem a kulcsot, a /v1/chat/completions, /v1/responses és /v1/messages végpontot együtt. A perc az első kérésedkor indul.
Az abban a percben érkező 121. kérés Too many requests. Retry in <n>s. üzenetet kap, és nem kerül semmibe. Az elutasított kérések is számítanak, ezért a várakozás nélkül újraküldő kliens a perc végéig elutasított marad. Várj az üzenetben szereplő <n> másodpercet.
A párhuzamosan küldött kéréseket nem utasítja el amiatt, hogy párhuzamosak. Sorban várnak, és sorban kapnak választ.
A GET /v1/models és a tokenszámláló végpontok nem számítanak.
Továbbiak a korlátokról és az egyenlegről, valamint arról, hol látod a saját egyenlegedet és használatodat: Korlátok és egyenleg Keys & usage
Mit érdemes újrapróbálni
Csak akkor küldj újra kérést, ha ugyanaz a kérés sikerülhet. Az OpenAI és az Anthropic SDK-k a 429 és 5xx válaszokat maguktól kétszer újrapróbálják; ennek módosításához állítsd a max_retries értéket (JavaScriptben maxRetries).
| Hiba | Újraküldhető? | Hogyan |
|---|---|---|
400, 404, 405, 413, 415, 422 | Nem. Először javítsd a kérést. | Az üzenet megnevezi a hibás mezőt, modellt vagy bemenetet. |
401 | Nem. Használj érvényes kulcsot. | Hozz létre vagy cserélj kulcsot a Keys & usage oldalon. |
429 Too many requests | Igen, a várakozás után. | Várj annyi másodpercet, amennyi az üzenetben áll, majd küldd el ugyanazt a kérést. |
429 Quota exceeded | Így nem. | Csökkentsd a max_tokens értékét, várd meg a napi újraindulást 00:00 UTC-kor, vagy tölts fel kreditet. |
429 Shannon Coder call quota reached | Igen, a következő ablakban. | Az ablakok 4 óránként indulnak 00:00 UTC-től. Másik modell azonnal válaszol. |
429 … temporarily busy | Igen. | Várj néhány másodpercet, majd minden további próbánál tovább. |
500, 502, 503 | Igen. | Várj 1 másodpercet, majd 2-t, 4-et és 8-at. Néhány próba után állj le, és jelentsd a kérésazonosítót. |
504 | Igen. | Küldd el a stream true értékével: az időkorlát a nem streamelt válaszokra vonatkozik. |
Az ezt a táblázatot követő újrapróbálkozási ciklus:
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); Hibák streamen belül
A stream az első bájttól 200 státuszú. Az utána bekövetkező hiba eseményként érkezik a streamen belül: error taggal rendelkező chunk a /v1/chat/completions, error esemény a /v1/messages, response.failed vagy error esemény a /v1/responses végponton. A stream záró eseményei ezután is megérkeznek. Az ilyen választ tekintsd sikertelennek, és küldd el újra a kérést, mint 5xx státusznál.
A modell kontextusablakánál hosszabb beszélgetést így jelzi a rendszer, invalid_request_error típussal és context_length_exceeded kóddal. Rövidítsd le a beszélgetést, mielőtt újra elküldöd.
A pontos kereteket a streaming oldal írja le. Streaming
Kérésazonosítók
Minden válasz, a hibák is, tartalmaz x-request-id fejlécet. Ez az érték az, amelyet a saját x-request-id fejlécedben küldtél, vagy 12 hexadecimális karakter, ha nem küldtél. Naplózd, és add meg, amikor segítséget kérsz egy kéréshez.