Preskočiť na obsah
Spracovanie chýb

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

Vráti stav 400 a toto telo:

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

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

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.