Ruka hadi kwenye maudhui
Ushughulikiaji wa Makosa

Ushughulikiaji wa Makosa

Ombi linalofeli hurudisha HTTP status code na mwili wa JSON wenye aina ya kosa na ujumbe. Ukurasa huu unaorodhesha kila hali, unaonyesha mwili wa kosa wa kila umbizo la API na unasema ni makosa gani yanafaa kutumwa tena.

SDK hutoa kitu cha kosa kinachobeba status code na fields za mwili. Ombi hili linataja model isiyokuwepo:

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

Linarudisha hali 400 na mwili huu:

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

Mwili wa kosa

Kuna miili miwili. /v1/messages hujibu kwa umbizo la Anthropic; kila endpoint nyingine hujibu kwa umbizo la OpenAI. Katika yote mawili, maelezo yako kwenye error.type na error.message, kwa hiyo msomaji mmoja anatosha endpoint zote.

401 Umbizo la OpenAI
{
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key",
    "code": "invalid_api_key",
    "param": null
  }
}
401 Umbizo la Anthropic
{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key"
  }
}
Field Aina Maelezo
error.type string Aina ya kosa. Tazama Aina za makosa hapa chini.
error.message string Sentensi kwa binadamu. Maandishi kwenye majedwali yaliyo hapa chini ni thabiti isipokuwa sehemu zake zinazobadilika, zinazoonyeshwa kama <id>, <n> au ….
error.code string | null Ipo kwenye baadhi ya makosa ya umbizo la OpenAI: invalid_api_key na 401, request_too_large na 413, context_length_exceeded mazungumzo yanapokuwa marefu mno, vinginevyo null au haipo. Amua kwanza kwa hali na error.type na uchukulie code kama nyongeza.
error.param null Ipo kwenye makosa yale yale kama code. Daima null.
type string Umbizo la Anthropic pekee. Daima error.

Aina za makosa

Aina Hali Maelezo
invalid_request_error 400, 413, 415, 422 Ombi lenyewe lina kosa: field, mwili, model id au input ambayo model haikubali. Badilisha ombi kabla ya kutuma tena.
authentication_error 401 API key haipo, haijulikani au imebatilishwa.
not_found_error 404 Path haipo.
rate_limit_error 429 Salio halitoshi kwa ombi, flood protection imelisimamisha, au model ina shughuli nyingi. Ujumbe unasema ni ipi.
api_error 500, 502, 503, 504 Ombi lilikuwa sawa na hitilafu iko upande wetu. Litume tena.
server_error 500 Ombi lilikuwa sawa na hitilafu iko upande wetu. Litume tena.

Status codes

Hali Aina Ujumbe Lini
400 invalid_request_error Failed to parse the request body as JSON: … Mwili si JSON halali.
400 invalid_request_error unknown model: <id> model si id iliyochapishwa. Kwenye /v1/responses pia wakati model haipo.
400 invalid_request_error No user message provided Viwango vya Shannon: ombi halina maandishi ya user.
400 invalid_request_error <id> does not accept image input Picha ilitumwa kwa model ya open-weight inayopangishwa isiyo na input ya picha.
400 invalid_request_error audio and video input are not supported by any hosted model Sehemu ya sauti au video ilitumwa kwa model ya open-weight inayopangishwa.
400 invalid_request_error <id> does not accept response_format Matokeo yaliyopangwa yaliombwa kutoka kwa model ya open-weight inayopangishwa isiyo nayo.
400 invalid_request_error <id> does not accept response_format json_schema; use json_object JSON schema ilitumwa kwa model ya open-weight inayopangishwa inayokubali json_object pekee.
400 invalid_request_error unknown reasoning effort '<value>'; expected off, low, medium or high Reasoning effort si moja ya thamani zilizoorodheshwa. Model za open-weight zinazopangishwa.
400 invalid_request_error count_tokens is available for the hosted open models; unknown model: <id> Kuhesabu tokens kuliombwa kwa model iliyo nje ya model za open-weight zinazopangishwa.
401 authentication_error Missing authentication Hakuna API key iliyotumwa.
401 authentication_error Invalid API key Key haijulikani, ilibadilishwa na mpya zaidi, au ilibatilishwa.
404 not_found_error Not Found Path haipo, kwa mfano /v1/embeddings.
405 api_error Method Not Allowed Path ipo lakini si kwa HTTP method hii.
413 invalid_request_error Failed to buffer the request body: … Mwili wa ombi ni mkubwa kuliko 32 MiB.
415 invalid_request_error Expected request with `Content-Type: application/json` Header ya Content-Type haipo au si application/json.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … Field inayohitajika haipo, kama messages, au field ina aina isiyo sahihi ya JSON.
429 rate_limit_error Quota exceeded. Upgrade your plan at shannon-ai.com/plan Kikomo cha output cha ombi ni kubwa kuliko kilichobaki kwenye salio lako.
429 rate_limit_error Too many requests. Retry in <n>s. Flood protection: maombi zaidi ya 120 ndani ya dakika moja kwenye akaunti yako. <n> ni idadi ya sekunde hadi dakika iishe.
429 rate_limit_error Shannon Coder call quota reached. Upgrade your plan at shannon-ai.com/plan shannon-coder-1 kwenye /v1/chat/completions na /v1/messages: wito wa Shannon Coder wa mpango wako kwa dirisha la sasa la saa 4 umetumika.
429 rate_limit_error Shannon routes are temporarily busy. Please retry. Model ina shughuli nyingi kwa sasa.
500 server_error The model backend failed to answer. Please retry. Model haikutoa jibu.
500 server_error An internal error occurred. Please retry. Hitilafu ya ndani wakati ombi lilikuwa linaandaliwa.
502 api_error The model backend failed to answer. Please retry. Model haikutoa jibu. Familia ya Shannon 3 na model za open-weight zinazopangishwa.
503 api_error Could not verify your quota right now. Please retry. Salio lako halikuweza kusomwa kwa sasa.
503 api_error token counting is temporarily unavailable for this model Kuhesabu tokens hakupatikani kwa model hii kwa sasa.
504 api_error upstream timed out Model ya open-weight inayopangishwa ilichukua muda mrefu kuliko kikomo cha muda cha ombi lisilo la stream.

Ukaguzi hufanyika kwa mpangilio huu: API key, mwili wa ombi, model id, flood protection, salio. Kwa hiyo ombi lenye key isiyo sahihi na mwili usio sahihi hurudisha 401. Ombi linalokataliwa kwa hali ya 4xx halitozwi.

Salio na flood protection

Kila ombi linahudumiwa kwa usawa: hakuna viwango vya rate wala quota tofauti ya API. Mambo mawili bado yanaweza kujibu 429, yote yenye aina rate_limit_error. Ujumbe unayatofautisha.

Salio

Salio lako ni kiasi cha mpango wa leo, ambacho hurejeshwa saa 00:00 UTC, na baada yake mikopo uliyonunua. Chat na API hutumia salio lile lile.

Kila ombi kwanza hutenga kikomo chake cha output: max_tokens, au max_output_tokens kwenye /v1/responses, 4,096 usipotuma yoyote. Jibu likikamilika, kiasi kilichotengwa hubadilishwa na kile ambacho ombi lilitumia. Kiasi hicho kisipoingia kwenye salio lililobaki, ombi hurudisha Quota exceeded kabla model haijaanza.

Maombi yanayoendeshwa kwa wakati mmoja kila moja hutenga kiasi chake. Kwa hiyo maombi mengi ya sambamba yenye max_tokens ya juu yanaweza kumaliza salio kwa muda mfupi, hata kila jibu likiwa fupi. max_tokens ndogo zaidi hutenga kidogo.

Flood protection

Flood protection inaruhusu maombi 120 kwa dakika kwa kila akaunti. Inahesabu akaunti, si key, kwenye /v1/chat/completions, /v1/responses na /v1/messages kwa pamoja. Dakika huanza na ombi lako la kwanza.

Ombi namba 121 ndani ya dakika hiyo hurudisha Too many requests. Retry in <n>s. na halina gharama. Maombi yaliyokataliwa pia yanahesabiwa, kwa hiyo client inayotuma tena bila kusubiri inaendelea kukataliwa hadi dakika iishe. Subiri sekunde <n> kutoka kwenye ujumbe.

Maombi yanayotumwa kwa sambamba hayakataliwi kwa sababu ni ya sambamba. Husubiri kwenye foleni na hujibiwa kwa zamu.

GET /v1/models na endpoint za kuhesabu tokens hazihesabiwi.

Zaidi kuhusu mipaka na salio, na mahali pa kuona salio na matumizi yako mwenyewe: Mipaka na salio Keys na matumizi

Nini cha kujaribu tena

Tuma ombi tena tu wakati ombi lile lile linaweza kufanikiwa. SDK za OpenAI na Anthropic tayari hujaribu tena majibu ya 429 na 5xx mara mbili zenyewe; weka max_retries (maxRetries kwenye JavaScript) ili kubadilisha hilo.

Kosa Tuma tena? Jinsi
400, 404, 405, 413, 415, 422 Hapana. Sahihisha ombi kwanza. Ujumbe unataja field, model au input iliyo na kosa.
401 Hapana. Tumia key halali. Unda au badilisha key kwenye ukurasa wa Keys na matumizi.
429 Too many requests Ndiyo, baada ya kusubiri. Subiri idadi ya sekunde iliyo kwenye ujumbe, kisha tuma ombi lile lile.
429 Quota exceeded Si kama ilivyo. Punguza max_tokens, subiri kurejeshwa kwa kila siku saa 00:00 UTC, au ongeza mikopo.
429 Shannon Coder call quota reached Ndiyo, kwenye dirisha linalofuata. Madirisha huanza kila saa 4 kuanzia 00:00 UTC. Model nyingine hujibu mara moja.
429 … temporarily busy Ndiyo. Subiri sekunde chache, kisha zaidi kwa kila jaribio linalofuata.
500, 502, 503 Ndiyo. Subiri sekunde 1, kisha 2, 4 na 8. Simama baada ya majaribio machache na uripoti request id.
504 Ndiyo. Litume na stream iliyowekwa kuwa true: kikomo cha muda kinatumika kwa majibu yasiyo ya stream.

Retry loop inayofuata jedwali hili:

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)

Makosa ndani ya stream

Stream ina hali 200 tangu byte yake ya kwanza. Hitilafu baada ya hapo hufika kama tukio ndani ya stream: chunk yenye member ya error kwenye /v1/chat/completions, tukio la error kwenye /v1/messages, tukio la response.failed au error kwenye /v1/responses. Matukio ya kufunga ya stream bado yanafuata. Chukulia jibu kama hilo kama lililoshindwa na utume ombi tena, kama kwa hali ya 5xx.

Mazungumzo marefu kuliko dirisha la muktadha la model huripotiwa kwa njia hii, na aina invalid_request_error na code context_length_exceeded. Fupisha mazungumzo kabla ya kutuma tena.

Frames kamili zimeelezwa kwenye streaming. Kutiririsha

Request ids

Kila jibu, pamoja na makosa, lina header ya x-request-id. Ni thamani uliyotuma kwenye header yako mwenyewe ya x-request-id, au herufi 12 za hexadecimal ukiwa hukutuma yoyote. Iandike kwenye log, na itaje unapoomba msaada kuhusu ombi.