Kalo te përmbajtja
Trajtimi i gabimeve

Trajtimi i gabimeve

Një kërkesë që dështon kthen një kod statusi HTTP dhe një trup JSON me një lloj gabimi dhe një mesazh. Kjo faqe liston çdo status, tregon trupin e gabimit të çdo formati API dhe thotë cilat gabime ia vlen t'i dërgoni përsëri.

SDK-të ngrenë një objekt gabimi që mban kodin e statusit dhe fushat e trupit. Kjo kërkesë emërton një model që nuk ekziston:

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

Kthen statusin 400 dhe këtë trup:

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

Trupi i gabimit

Ka dy trupa. /v1/messages përgjigjet në formatin Anthropic; çdo endpoint tjetër përgjigjet në formatin OpenAI. Në të dyja, detajet janë te error.type dhe error.message, kështu që një lexues i vetëm shërben për të gjitha endpoint-et.

401 Formati OpenAI
{
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key",
    "code": "invalid_api_key",
    "param": null
  }
}
401 Formati Anthropic
{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key"
  }
}
Fusha Lloji Përshkrimi
error.type string Lloji i gabimit. Shihni Llojet e gabimeve më poshtë.
error.message string Një fjali për njeriun. Tekstet në tabelat më poshtë janë të qëndrueshme përveç pjesëve të ndryshueshme, të shfaqura si <id>, <n> ose ….
error.code string | null I pranishëm te disa gabime të formatit OpenAI: invalid_api_key me 401, request_too_large me 413, context_length_exceeded kur një bisedë është shumë e gjatë, përndryshe null ose mungon. Vendosni fillimisht sipas statusit dhe error.type dhe trajtojeni code si shtesë.
error.param null I pranishëm te të njëjtat gabime si code. Gjithmonë null.
type string Vetëm formati Anthropic. Gjithmonë error.

Llojet e gabimeve

Lloji Statuset Përshkrimi
invalid_request_error 400, 413, 415, 422 Vetë kërkesa është e gabuar: një fushë, trupi, id-ja e modelit ose një hyrje që modeli nuk e pranon. Ndryshojeni kërkesën para se ta dërgoni përsëri.
authentication_error 401 Çelësi API mungon, është i panjohur ose i shfuqizuar.
not_found_error 404 Rruga nuk ekziston.
rate_limit_error 429 Bilanci nuk e mbulon kërkesën, mbrojtja nga vërshimi i kërkesave e ndaloi, ose modeli është i zënë. Mesazhi thotë cila nga këto.
api_error 500, 502, 503, 504 Kërkesa ishte në rregull dhe dështimi është nga ana jonë. Dërgojeni përsëri.
server_error 500 Kërkesa ishte në rregull dhe dështimi është nga ana jonë. Dërgojeni përsëri.

Kodet e statusit

Statusi Lloji Mesazhi Kur
400 invalid_request_error Failed to parse the request body as JSON: … Trupi nuk është JSON i vlefshëm.
400 invalid_request_error unknown model: <id> model nuk është id e publikuar. Në /v1/responses edhe kur model mungon.
400 invalid_request_error No user message provided Nivelet Shannon: kërkesa nuk përmban tekst përdoruesi.
400 invalid_request_error <id> does not accept image input Një imazh iu dërgua një modeli open-weight të hostuar pa hyrje imazhi.
400 invalid_request_error audio and video input are not supported by any hosted model Një pjesë audio ose video iu dërgua një modeli open-weight të hostuar.
400 invalid_request_error <id> does not accept response_format Dalje e strukturuar iu kërkua një modeli open-weight të hostuar që nuk e ka.
400 invalid_request_error <id> does not accept response_format json_schema; use json_object Një skemë JSON iu dërgua një modeli open-weight të hostuar që pranon vetëm json_object.
400 invalid_request_error unknown reasoning effort '<value>'; expected off, low, medium or high Përpjekja e arsyetimit nuk është një nga vlerat e listuara. Modelet open-weight të hostuara.
400 invalid_request_error count_tokens is available for the hosted open models; unknown model: <id> Numërimi i tokens-ave u kërkua për një model jashtë modeleve open-weight të hostuara.
401 authentication_error Missing authentication Nuk u dërgua çelës API.
401 authentication_error Invalid API key Çelësi është i panjohur, u zëvendësua me një më të ri, ose u shfuqizua.
404 not_found_error Not Found Rruga nuk ekziston, për shembull /v1/embeddings.
405 api_error Method Not Allowed Rruga ekziston por jo me këtë metodë HTTP.
413 invalid_request_error Failed to buffer the request body: … Trupi i kërkesës është më i madh se 32 MiB.
415 invalid_request_error Expected request with `Content-Type: application/json` Header-i Content-Type mungon ose nuk është application/json.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … Mungon një fushë e detyrueshme, si messages, ose një fushë ka lloj JSON të gabuar.
429 rate_limit_error Quota exceeded. Upgrade your plan at shannon-ai.com/plan Kufiri i daljes së kërkesës është më i madh se ç'ka mbetur nga bilanci juaj.
429 rate_limit_error Too many requests. Retry in <n>s. Mbrojtja nga vërshimi i kërkesave: më shumë se 120 kërkesa në një minutë në llogarinë tuaj. <n> është numri i sekondave deri në fund të minutës.
429 rate_limit_error Shannon Coder call quota reached. Upgrade your plan at shannon-ai.com/plan shannon-coder-1 në /v1/chat/completions dhe /v1/messages: thirrjet Shannon Coder të planit tuaj për dritaren aktuale 4-orëshe janë shfrytëzuar.
429 rate_limit_error Shannon routes are temporarily busy. Please retry. Modeli është i zënë në këtë çast.
500 server_error The model backend failed to answer. Please retry. Modeli nuk prodhoi përgjigje.
500 server_error An internal error occurred. Please retry. Një dështim i brendshëm gjatë përgatitjes së kërkesës.
502 api_error The model backend failed to answer. Please retry. Modeli nuk prodhoi përgjigje. Familja Shannon 3 dhe modelet open-weight të hostuara.
503 api_error Could not verify your quota right now. Please retry. Bilanci juaj nuk u lexua dot në këtë çast.
503 api_error token counting is temporarily unavailable for this model Numërimi i tokens-ave nuk është i disponueshëm për këtë model në këtë çast.
504 api_error upstream timed out Një model open-weight i hostuar zgjati më shumë se kufiri i kohës i një kërkese pa stream.

Kontrollet kryhen në këtë radhë: çelësi API, trupi i kërkesës, id-ja e modelit, mbrojtja nga vërshimi i kërkesave, bilanci. Një kërkesë me çelës të gabuar dhe trup të gabuar kthen pra 401. Një kërkesë e refuzuar me status 4xx nuk faturohet.

Bilanci dhe mbrojtja nga vërshimi i kërkesave

Çdo kërkesë shërbehet njësoj: nuk ka nivele shpejtësie dhe nuk ka kuotë të veçantë API. Dy gjëra prapë mund të përgjigjen me 429, të dyja me llojin rate_limit_error. Mesazhi i dallon.

Bilanci

Bilanci juaj është kuota e planit për sot, që rivendoset në 00:00 UTC, dhe pas saj krediti juaj i blerë. Biseda dhe API tërheqin nga i njëjti bilanc.

Çdo kërkesë rezervon fillimisht kufirin e vet të daljes: max_tokens, ose max_output_tokens në /v1/responses, 4,096 kur nuk dërgoni asnjërin. Kur përgjigjja është e plotë, sasia e rezervuar zëvendësohet me atë që përdori kërkesa. Nëse sasia nuk ngjit në bilancin që ka mbetur, kërkesa kthen Quota exceeded para se të nisë modeli.

Kërkesat që ekzekutohen në të njëjtën kohë rezervojnë secila sasinë e vet. Shumë kërkesa paralele me max_tokens të lartë mund ta shterojnë pra bilancin për një çast, edhe kur çdo përgjigje është e shkurtër. Një max_tokens më i ulët rezervon më pak.

Mbrojtja nga vërshimi i kërkesave

Mbrojtja nga vërshimi i kërkesave lejon 120 kërkesa në minutë për llogari. Numëron llogarinë, jo çelësin, në /v1/chat/completions, /v1/responses dhe /v1/messages së bashku. Minuta fillon me kërkesën tuaj të parë.

Kërkesa numër 121 brenda asaj minute kthen Too many requests. Retry in <n>s. dhe nuk kushton asgjë. Edhe kërkesat e refuzuara numërohen, kështu që një klient që dërgon përsëri pa pritur mbetet i refuzuar derisa të mbarojë minuta. Prisni <n> sekondat nga mesazhi.

Kërkesat e dërguara paralelisht nuk refuzohen për shkak se janë paralele. Presin në radhë dhe marrin përgjigje me radhë.

GET /v1/models dhe endpoint-et e numërimit të tokens-ave nuk numërohen.

Më shumë për kufijtë dhe bilancin, dhe ku mund ta shihni bilancin dhe përdorimin tuaj: Kufijtë dhe bilanci Çelësat dhe përdorimi

Çfarë ta provoni përsëri

Dërgoni një kërkesë përsëri vetëm kur e njëjta kërkesë mund të ketë sukses. SDK-të OpenAI dhe Anthropic i provojnë vetë dy herë përgjigjet 429 dhe 5xx; caktoni max_retries (maxRetries në JavaScript) për ta ndryshuar.

Gabimi Ta dërgoj përsëri? Si
400, 404, 405, 413, 415, 422 Jo. Së pari korrigjojeni kërkesën. Mesazhi emërton fushën, modelin ose hyrjen që është e gabuar.
401 Jo. Përdorni një çelës të vlefshëm. Krijoni ose zëvendësoni çelësin në faqen Çelësat dhe përdorimi.
429 Too many requests Po, pas pritjes. Prisni numrin e sekondave në mesazh, pastaj dërgoni të njëjtën kërkesë.
429 Quota exceeded Jo siç është. Ulni max_tokens, prisni rivendosjen ditore në 00:00 UTC, ose shtoni kredi.
429 Shannon Coder call quota reached Po, në dritaren tjetër. Dritaret fillojnë çdo 4 orë nga 00:00 UTC. Një model tjetër përgjigjet menjëherë.
429 … temporarily busy Po. Prisni disa sekonda, pastaj më shumë në çdo përpjekje të mëtejshme.
500, 502, 503 Po. Prisni 1 sekondë, pastaj 2, 4 dhe 8. Ndaloni pas disa përpjekjesh dhe raportoni id-në e kërkesës.
504 Po. Dërgojeni me stream të vendosur në true: kufiri i kohës vlen për përgjigjet pa stream.

Një cikël riprovimi që ndjek këtë tabelë:

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)

Gabimet brenda një stream-i

Një stream ka statusin 200 nga byte-i i parë. Një dështim pas kësaj arrin si ngjarje brenda stream-it: një pjesë me anëtar error në /v1/chat/completions, një ngjarje error në /v1/messages, një ngjarje response.failed ose error në /v1/responses. Ngjarjet mbyllëse të stream-it prapë vijnë pas. Trajtojeni një përgjigje të tillë si të dështuar dhe dërgoni kërkesën përsëri, si për një status 5xx.

Një bisedë më e gjatë se dritarja e kontekstit të modelit raportohet në këtë mënyrë, me llojin invalid_request_error dhe kodin context_length_exceeded. Shkurtojeni bisedën para se ta dërgoni përsëri.

Frame-et e sakta përshkruhen te streaming. Transmetim

Id-të e kërkesave

Çdo përgjigje, përfshirë gabimet, ka një header x-request-id. Është vlera që dërguat në header-in tuaj x-request-id, ose 12 karaktere heksadecimale kur nuk dërguat asnjë. Regjistrojeni dhe citojeni kur kërkoni ndihmë për një kërkesë.