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 import OpenAI from "openai";
const client = new OpenAI({
apiKey: "YOUR_API_KEY",
baseURL: "https://api.shannon-ai.com/v1",
});
try {
await client.chat.completions.create({
model: "no-such-model",
messages: [{ role: "user", content: "Hello" }],
});
} catch (error) {
if (!(error instanceof OpenAI.APIError)) throw error;
console.log(error.status); // 400
console.log(error.type); // invalid_request_error
console.log(error.error.message); // unknown model: no-such-model
} curl -i https://api.shannon-ai.com/v1/chat/completions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "no-such-model",
"messages": [{"role": "user", "content": "Hello"}]
}' Linarudisha hali 400 na mwili huu:
{
"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.
{
"error": {
"type": "authentication_error",
"message": "Invalid API key",
"code": "invalid_api_key",
"param": null
}
} {
"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) import OpenAI from "openai";
// maxRetries: 0 — this loop does the retrying, the SDK does not add its own.
const client = new OpenAI({ apiKey: "YOUR_API_KEY", baseURL: "https://api.shannon-ai.com/v1", maxRetries: 0 });
const sleep = (seconds) => new Promise((resolve) => setTimeout(resolve, seconds * 1000));
async function createWithRetry(request, attempts = 5) {
for (let attempt = 0; attempt < attempts; attempt++) {
try {
return await client.chat.completions.create(request);
} catch (error) {
const text = String(error.message);
const flood = text.match(/Retry in (\d+)s/);
if (error.status === 429 && flood) {
await sleep(Number(flood[1])); // flood protection: wait out the minute
} else if (error.status === 429 && text.includes("temporarily busy")) {
await sleep(2 ** attempt);
} else if (error.status >= 500 || error instanceof OpenAI.APIConnectionError) {
await sleep(2 ** attempt); // 1, 2, 4, 8 seconds
} else {
throw error; // wrong request, wrong key or balance
}
}
}
throw new Error("the request failed after all attempts");
}
const response = await createWithRetry({
model: "shannon-3",
messages: [{ role: "user", content: "Hello" }],
});
console.log(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.