Preskoči na vsebino
Obravnava napak

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

Vrne status 400 in to telo:

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

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

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.