Preskoči na sadržaj
Upravljanje greškama

Upravljanje greškama

Zahtev koji ne uspe vraća HTTP statusni kod i JSON telo sa tipom greške i porukom. Ova stranica navodi svaki status, prikazuje telo greške za svaki API format i kaže koje greške vredi ponoviti.

SDK-ovi podižu objekat greške koji nosi statusni kod i polja tela. Ovaj zahtev navodi model koji ne postoji:

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

Vraća status 400 i ovo telo:

400 JSON
{
  "error": {
    "type": "invalid_request_error",
    "message": "unknown model: no-such-model"
  }
}

Telo greške

Postoje dva tela. /v1/messages odgovara u Anthropic formatu; svaki drugi endpoint odgovara u OpenAI formatu. U oba su detalji u error.type i error.message, pa jedan čitač služi svim endpointima.

401 OpenAI format
{
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key",
    "code": "invalid_api_key",
    "param": null
  }
}
401 Anthropic format
{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key"
  }
}
Polje Tip Opis
error.type string Vrsta greške. Pogledajte Tipovi grešaka ispod.
error.message string Rečenica za čoveka. Tekstovi u tabelama ispod su stabilni do svojih promenljivih delova, prikazanih kao <id>, <n> ili ….
error.code string | null Prisutno na nekim greškama OpenAI formata: invalid_api_key uz 401, request_too_large uz 413, context_length_exceeded kada je razgovor predugačak, inače null ili odsutno. Prvo odlučujte po statusu i error.type, a code tretirajte kao dodatak.
error.param null Prisutno na istim greškama kao code. Uvek null.
type string Samo Anthropic format. Uvek error.

Tipovi grešaka

Tip Statusi Opis
invalid_request_error 400, 413, 415, 422 Sâm zahtev je pogrešan: polje, telo, id modela ili ulaz koji model ne prima. Promenite zahtev pre ponovnog slanja.
authentication_error 401 API ključ nedostaje, nepoznat je ili opozvan.
not_found_error 404 Putanja ne postoji.
rate_limit_error 429 Stanje ne pokriva zahtev, zaštita od flooda ga je zaustavila ili je model zauzet. Poruka kaže šta je od toga.
api_error 500, 502, 503, 504 Zahtev je bio u redu, a kvar je na našoj strani. Pošaljite ga ponovo.
server_error 500 Zahtev je bio u redu, a kvar je na našoj strani. Pošaljite ga ponovo.

Statusni kodovi

Status Tip Poruka Kada
400 invalid_request_error Failed to parse the request body as JSON: … Telo nije važeći JSON.
400 invalid_request_error unknown model: <id> model nije objavljeni id. Na /v1/responses i kada model nedostaje.
400 invalid_request_error No user message provided Shannon nivoi: zahtev ne sadrži korisnički tekst.
400 invalid_request_error <id> does not accept image input Slika je poslata hostovanom open-weight modelu bez podrške za sliku na ulazu.
400 invalid_request_error audio and video input are not supported by any hosted model Audio ili video deo poslat je hostovanom open-weight modelu.
400 invalid_request_error <id> does not accept response_format Strukturirani izlaz je zatražen od hostovanog open-weight modela koji ga nema.
400 invalid_request_error <id> does not accept response_format json_schema; use json_object JSON šema je poslata hostovanom open-weight modelu koji prima samo json_object.
400 invalid_request_error unknown reasoning effort '<value>'; expected off, low, medium or high Napor pri zaključivanju nije jedna od navedenih vrednosti. Hostovani open-weight modeli.
400 invalid_request_error count_tokens is available for the hosted open models; unknown model: <id> Brojanje tokena zatraženo je za model van hostovanih open-weight modela.
401 authentication_error Missing authentication API ključ nije poslat.
401 authentication_error Invalid API key Ključ je nepoznat, zamenjen je novijim ili je opozvan.
404 not_found_error Not Found Putanja ne postoji, na primer /v1/embeddings.
405 api_error Method Not Allowed Putanja postoji, ali ne sa ovim HTTP metodom.
413 invalid_request_error Failed to buffer the request body: … Telo zahteva je veće od 32 MiB.
415 invalid_request_error Expected request with `Content-Type: application/json` Zaglavlje Content-Type nedostaje ili nije application/json.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … Obavezno polje nedostaje, kao što je messages, ili polje ima pogrešan JSON tip.
429 rate_limit_error Quota exceeded. Upgrade your plan at shannon-ai.com/plan Ograničenje izlaza zahteva je veće od onoga što je preostalo na vašem stanju.
429 rate_limit_error Too many requests. Retry in <n>s. Zaštita od flooda: više od 120 zahteva u jednom minutu na vašem nalogu. <n> je broj sekundi do kraja minuta.
429 rate_limit_error Shannon Coder call quota reached. Upgrade your plan at shannon-ai.com/plan shannon-coder-1 na /v1/chat/completions i /v1/messages: Shannon Coder pozivi vašeg plana za tekući 4-časovni period su potrošeni.
429 rate_limit_error Shannon routes are temporarily busy. Please retry. Model je u ovom trenutku zauzet.
500 server_error The model backend failed to answer. Please retry. Model nije proizveo odgovor.
500 server_error An internal error occurred. Please retry. Interni kvar dok se zahtev pripremao.
502 api_error The model backend failed to answer. Please retry. Model nije proizveo odgovor. Porodica Shannon 3 i hostovani open-weight modeli.
503 api_error Could not verify your quota right now. Please retry. Vaše stanje trenutno nije moglo da se pročita.
503 api_error token counting is temporarily unavailable for this model Brojanje tokena trenutno nije dostupno za ovaj model.
504 api_error upstream timed out Hostovani open-weight model je trajao duže od vremenskog ograničenja zahteva koji nije strimovan.

Provere idu ovim redom: API ključ, telo zahteva, id modela, zaštita od flooda, stanje. Zahtev sa pogrešnim ključem i pogrešnim telom zato vraća 401. Zahtev koji se odbije sa statusom 4xx ne naplaćuje se.

Stanje i zaštita od flooda

Svaki zahtev se opslužuje jednako: nema nivoa ograničenja brzine ni posebne API kvote. Dve stvari ipak mogu odgovoriti sa 429, obe sa tipom rate_limit_error. Poruka ih razlikuje.

Stanje

Vaše stanje je današnji limit plana, koji se resetuje u 00:00 UTC, a posle njega vaš kupljeni kredit. Čet i API crpe isto stanje.

Svaki zahtev prvo izdvaja svoje ograničenje izlaza: max_tokens, ili max_output_tokens na /v1/responses, 4,096 kada ne pošaljete nijedno. Kada je odgovor završen, izdvojeni iznos se zamenjuje onim što je zahtev iskoristio. Ako se iznos ne uklapa u preostalo stanje, zahtev vraća Quota exceeded pre nego što model počne.

Zahtevi koji rade istovremeno izdvajaju svaki svoj iznos. Mnogo paralelnih zahteva sa visokim max_tokens zato može načas potrošiti stanje, čak i kada je svaki odgovor kratak. Niži max_tokens izdvaja manje.

Zaštita od flooda

Zaštita od flooda dozvoljava 120 zahteva u minuti po nalogu. Računa nalog, a ne ključ, preko /v1/chat/completions, /v1/responses i /v1/messages zajedno. Minut počinje vašim prvim zahtevom.

Zahtev broj 121 unutar tog minuta vraća Too many requests. Retry in <n>s. i ne košta ništa. Odbijeni zahtevi se takođe računaju, pa klijent koji ponovo šalje bez čekanja ostaje odbijen dok minut ne istekne. Sačekajte <n> sekundi iz poruke.

Zahtevi poslati paralelno ne odbijaju se zato što su paralelni. Čekaju u redu i odgovara im se redom.

GET /v1/models i endpointi za brojanje tokena se ne računaju.

Više o ograničenjima i stanju, i gde da vidite svoje stanje i upotrebu: Ograničenja i stanje Ključevi i upotreba

Šta ponoviti

Ponovo šaljite zahtev samo kada isti zahtev može da uspe. OpenAI i Anthropic SDK-ovi već sami dvaput ponavljaju odgovore 429 i 5xx; postavite max_retries (maxRetries u JavaScriptu) da to promenite.

Greška Poslati ponovo? Kako
400, 404, 405, 413, 415, 422 Ne. Prvo ispravite zahtev. Poruka navodi polje, model ili ulaz koji je pogrešan.
401 Ne. Koristite važeći ključ. Napravite ili zamenite ključ na stranici Ključevi i upotreba.
429 Too many requests Da, posle čekanja. Sačekajte broj sekundi iz poruke, pa pošaljite isti zahtev.
429 Quota exceeded Ne ovako kako jeste. Smanjite max_tokens, sačekajte dnevni reset u 00:00 UTC ili dodajte kredit.
429 Shannon Coder call quota reached Da, u sledećem periodu. Periodi počinju na svaka 4 sata od 00:00 UTC. Drugi model odgovara odmah.
429 … temporarily busy Da. Sačekajte nekoliko sekundi, pa duže pri svakom daljem pokušaju.
500, 502, 503 Da. Sačekajte 1 sekundu, pa 2, 4 i 8. Stanite posle nekoliko pokušaja i prijavite id zahteva.
504 Da. Pošaljite ga sa stream postavljenim na true: vremensko ograničenje važi za odgovore koji nisu strimovani.

Petlja ponavljanja koja prati ovu tabelu:

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)

Greške unutar streama

Stream ima status 200 od prvog bajta. Greška posle toga stiže kao događaj unutar streama: deo sa članom error na /v1/chat/completions, događaj error na /v1/messages, događaj response.failed ili error na /v1/responses. Završni događaji streama i dalje slede. Smatrajte takav odgovor neuspelim i ponovo pošaljite zahtev, kao za status 5xx.

Razgovor duži od kontekstnog prozora modela prijavljuje se na ovaj način, sa tipom invalid_request_error i kodom context_length_exceeded. Skratite razgovor pre ponovnog slanja.

Tačni frameovi opisani su uz streaming. Streaming

Id-jevi zahteva

Svaki odgovor, uključujući greške, ima zaglavlje x-request-id. To je vrednost koju ste poslali u svom zaglavlju x-request-id, ili 12 heksadecimalnih znakova kada niste poslali nijednu. Beležite je i navedite je kada tražite pomoć oko zahteva.