Ugrás a tartalomra
Hibakezelés

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

400 státuszt és ezt a törzset adja vissza:

400 JSON
{
  "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.

401 OpenAI formátum
{
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key",
    "code": "invalid_api_key",
    "param": null
  }
}
401 Anthropic formátum
{
  "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)

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.