Aqbeż għall-kontenut
Ġestjoni tal-iżbalji

Ġestjoni tal-iżbalji

Talba li tfalli tagħti lura kodiċi ta' status HTTP u body JSON b'tip ta' żball u messaġġ. Din il-paġna telenka kull status, turi l-body tal-iżball ta' kull format tal-API u tgħid liema żbalji jistħoqqilhom li jintbagħtu mill-ġdid.

L-SDKs jgħollu oġġett ta' żball li jġorr il-kodiċi ta' status u l-kampi tal-body. Din it-talba tisemma mudell li ma jeżistix:

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

Tagħti lura status 400 u dan il-body:

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

Body tal-iżball

Hemm żewġ bodies. /v1/messages iwieġeb fil-format Anthropic; kull endpoint ieħor iwieġeb fil-format OpenAI. Fiż-żewġ każijiet, id-dettalji jinsabu f'error.type u error.message, għalhekk qarrej wieħed iservi l-endpoints kollha.

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"
  }
}
Qasam Tip Deskrizzjoni
error.type string It-tip ta' żball. Ara t-Tipi ta' żbalji hawn taħt.
error.message string Sentenza għal persuna. It-testi fit-tabelli hawn taħt huma stabbli ħlief għall-partijiet varjabbli tagħhom, murija bħala <id>, <n> jew ….
error.code string | null Preżenti fuq xi żbalji tal-format OpenAI: invalid_api_key b'401, request_too_large b'413, context_length_exceeded meta konversazzjoni tkun twila wisq, inkella null jew assenti. Iddeċiedi skont l-istatus u error.type l-ewwel u qis code bħala żieda.
error.param null Preżenti fuq l-istess żbalji bħal code. Dejjem null.
type string Format Anthropic biss. Dejjem error.

Tipi ta' żbalji

Tip Stati Deskrizzjoni
invalid_request_error 400, 413, 415, 422 It-talba nnifisha hija ħażina: qasam, il-body, l-id tal-mudell jew input li l-mudell ma jaċċettax. Biddel it-talba qabel ma tibgħatha mill-ġdid.
authentication_error 401 Iċ-ċavetta tal-API hija nieqsa, mhix magħrufa jew ġiet irrevokata.
not_found_error 404 Il-path ma jeżistix.
rate_limit_error 429 Il-bilanċ ma jkoprix it-talba, il-protezzjoni mill-flood waqqfitha, jew il-mudell huwa impenjat. Il-messaġġ jgħid liema.
api_error 500, 502, 503, 504 It-talba kienet tajba u l-falliment huwa min-naħa tagħna. Ibgħatha mill-ġdid.
server_error 500 It-talba kienet tajba u l-falliment huwa min-naħa tagħna. Ibgħatha mill-ġdid.

Kodiċijiet ta' status

Status Tip Messaġġ Meta
400 invalid_request_error Failed to parse the request body as JSON: … Il-body mhuwiex JSON validu.
400 invalid_request_error unknown model: <id> model mhuwiex id ippubblikat. Fuq /v1/responses anke meta model ikun nieqes.
400 invalid_request_error No user message provided Livelli Shannon: it-talba ma fiha l-ebda test tal-utent.
400 invalid_request_error <id> does not accept image input Intbagħtet immaġni lil mudell open-weight ospitat mingħajr input ta' immaġni.
400 invalid_request_error audio and video input are not supported by any hosted model Parti awdjo jew vidjo ntbagħtet lil mudell open-weight ospitat.
400 invalid_request_error <id> does not accept response_format Intalab output strutturat minn mudell open-weight ospitat li ma jsapportjahx.
400 invalid_request_error <id> does not accept response_format json_schema; use json_object Intbagħat JSON schema lil mudell open-weight ospitat li jaċċetta json_object biss.
400 invalid_request_error unknown reasoning effort '<value>'; expected off, low, medium or high L-isforz tar-raġunament mhuwiex wieħed mill-valuri elenkati. Mudelli open-weight ospitati.
400 invalid_request_error count_tokens is available for the hosted open models; unknown model: <id> Intalab l-għadd ta' tokens għal mudell barra l-mudelli open-weight ospitati.
401 authentication_error Missing authentication Ma ntbagħtet l-ebda ċavetta tal-API.
401 authentication_error Invalid API key Iċ-ċavetta mhijiex magħrufa, ġiet sostitwita b'waħda ġdida, jew ġiet irrevokata.
404 not_found_error Not Found Il-path ma jeżistix, pereżempju /v1/embeddings.
405 api_error Method Not Allowed Il-path jeżisti iżda mhux b'dan il-metodu HTTP.
413 invalid_request_error Failed to buffer the request body: … Il-body tat-talba huwa akbar minn 32 MiB.
415 invalid_request_error Expected request with `Content-Type: application/json` L-header Content-Type hu nieqes jew mhuwiex application/json.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … Qasam meħtieġ huwa nieqes, bħal messages, jew qasam għandu tip JSON ħażin.
429 rate_limit_error Quota exceeded. Upgrade your plan at shannon-ai.com/plan Il-limitu tal-output tat-talba huwa akbar minn dak li fadal mill-bilanċ tiegħek.
429 rate_limit_error Too many requests. Retry in <n>s. Protezzjoni mill-flood: aktar minn 120 talba f'minuta waħda fuq il-kont tiegħek. <n> huwa l-għadd ta' sekondi sa tmiem il-minuta.
429 rate_limit_error Shannon Coder call quota reached. Upgrade your plan at shannon-ai.com/plan shannon-coder-1 fuq /v1/chat/completions u /v1/messages: is-sejħiet ta' Shannon Coder tal-pjan tiegħek għat-tieqa kurrenti ta' 4 sigħat intużaw.
429 rate_limit_error Shannon routes are temporarily busy. Please retry. Il-mudell huwa impenjat f'dan il-mument.
500 server_error The model backend failed to answer. Please retry. Il-mudell ma pproduċa l-ebda tweġiba.
500 server_error An internal error occurred. Please retry. Falliment intern waqt li t-talba kienet qed tiġi ppreparata.
502 api_error The model backend failed to answer. Please retry. Il-mudell ma pproduċa l-ebda tweġiba. Familja Shannon 3 u mudelli open-weight ospitati.
503 api_error Could not verify your quota right now. Please retry. Il-bilanċ tiegħek ma setax jinqara f'dan il-mument.
503 api_error token counting is temporarily unavailable for this model L-għadd ta' tokens mhuwiex disponibbli għal dan il-mudell f'dan il-mument.
504 api_error upstream timed out Mudell open-weight ospitat dam aktar mil-limitu tal-ħin ta' talba li ma tiġix fi stream.

Il-verifiki jmorru f'dan l-ordni: ċavetta tal-API, body tat-talba, id tal-mudell, protezzjoni mill-flood, bilanċ. Talba b'ċavetta ħażina u body ħażin għalhekk tagħti lura 401. Talba miċħuda bi status 4xx ma titħallasx.

Bilanċ u protezzjoni mill-flood

Kull talba tiġi servuta bl-istess mod: m'hemm l-ebda livelli ta' rate u l-ebda kwota separata tal-API. Żewġ affarijiet xorta jistgħu jwieġbu b'429, it-tnejn bit-tip rate_limit_error. Il-messaġġ jgħid liema huma.

Bilanċ

Il-bilanċ tiegħek huwa l-kwota tal-pjan ta' illum, li terġa' tibda fi 00:00 UTC, u warajha l-kreditu imxri tiegħek. Il-chat u l-API jieħdu mill-istess bilanċ.

Kull talba l-ewwel tirriżerva l-limitu tal-output tagħha: max_tokens, jew max_output_tokens fuq /v1/responses, 4,096 meta ma tibgħat l-ebda wieħed. Meta t-tweġiba tkun kompluta, l-ammont irriżervat jiġi mibdul b'dak li użat it-talba. Jekk l-ammont ma jidħolx fil-bilanċ li fadal, it-talba tagħti lura Quota exceeded qabel ma jibda l-mudell.

Talbiet li jaħdmu fl-istess ħin jirriżervaw kull wieħed l-ammont tiegħu. Ħafna talbiet paralleli b'max_tokens għoli jistgħu għalhekk jeżawrixxu l-bilanċ għal mument, anke meta kull tweġiba tkun qasira. max_tokens aktar baxx jirriżerva anqas.

Protezzjoni mill-flood

Il-protezzjoni mill-flood tħalli 120 talba kull minuta għal kull kont. Tgħodd il-kont, mhux iċ-ċavetta, fuq /v1/chat/completions, /v1/responses u /v1/messages flimkien. Il-minuta tibda bl-ewwel talba tiegħek.

Talba numru 121 ġewwa dik il-minuta tagħti lura Too many requests. Retry in <n>s. u ma tiswa xejn. It-talbiet miċħuda jingħaddu wkoll, għalhekk klijent li jibgħat mill-ġdid mingħajr ma jistenna jibqa' miċħud sakemm tgħaddi l-minuta. Stenna l-<n> sekondi mill-messaġġ.

It-talbiet mibgħuta b'mod parallel ma jiġux miċħuda talli huma paralleli. Jistennew fil-kju u jitwieġbu bit-turn.

GET /v1/models u l-endpoints tal-għadd ta' tokens ma jingħaddux.

Aktar dwar il-limiti u l-bilanċ, u fejn tara l-bilanċ u l-użu tiegħek: Limiti u bilanċ Ċwievet u użu

X'għandek terġa' tipprova

Ibgħat talba mill-ġdid biss meta l-istess talba tista' tirnexxi. L-SDKs ta' OpenAI u Anthropic diġà jerġgħu jippruvaw tweġibiet 429 u 5xx darbtejn waħedhom; issettja max_retries (maxRetries f'JavaScript) biex tbiddel dan.

Żball Terġa' tibgħat? Kif
400, 404, 405, 413, 415, 422 Le. Ikkoreġi t-talba l-ewwel. Il-messaġġ isemmi l-qasam, il-mudell jew l-input li huwa ħażin.
401 Le. Uża ċavetta valida. Oħloq jew ibdel iċ-ċavetta fil-paġna Keys & usage.
429 Too many requests Iva, wara l-istennija. Stenna l-għadd ta' sekondi li hemm fil-messaġġ, imbagħad ibgħat l-istess talba.
429 Quota exceeded Mhux kif inhi. Naqqas max_tokens, stenna r-reset ta' kuljum fi 00:00 UTC, jew żid kreditu.
429 Shannon Coder call quota reached Iva, fit-tieqa li jmiss. It-twieqi jibdew kull 4 sigħat minn 00:00 UTC. Mudell ieħor iwieġeb minnufih.
429 … temporarily busy Iva. Stenna ftit sekondi, imbagħad aktar f'kull tentattiv ieħor.
500, 502, 503 Iva. Stenna sekonda 1, imbagħad 2, 4 u 8. Waqqaf wara ftit tentattivi u rrapporta l-id tat-talba.
504 Iva. Ibgħatha b'stream issettjat għal true: il-limitu tal-ħin japplika għal tweġibiet li ma jiġux fi stream.

Linja ta' retry li ssegwi din it-tabella:

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)

Żbalji ġewwa stream

Stream għandu status 200 mill-ewwel byte tiegħu. Falliment wara dan jasal bħala avveniment ġewwa l-istream: chunk b'membru error fuq /v1/chat/completions, avveniment error fuq /v1/messages, avveniment response.failed jew error fuq /v1/responses. L-avvenimenti tal-għeluq tal-istream xorta jiġu warajh. Qis tweġiba bħal din bħala fallita u ibgħat it-talba mill-ġdid, bħal ma tagħmel b'status 5xx.

Konversazzjoni li hija itwal mit-tieqa tal-kuntest tal-mudell tiġi rrapportata b'dan il-mod, bit-tip invalid_request_error u l-kodiċi context_length_exceeded. Qassar il-konversazzjoni qabel ma tibgħat mill-ġdid.

Il-frames eżatti huma deskritti mal-streaming. Streaming

Ids tat-talbiet

Kull tweġiba, inklużi l-iżbalji, għandha header x-request-id. Huwa l-valur li bgħatt fil-header x-request-id tiegħek, jew 12-il karattru eżadeċimali meta ma bgħatt l-ebda wieħed. Irreġistrah, u ċitah meta titlob għajnuna b'talba.