Идораи хатогиҳо
Дархосте, ки ноком мешавад, рамзи ҳолати HTTP ва бадани JSON бо навъи хатогӣ ва паём бармегардонад. Ин саҳифа ҳар ҳолатро номбар мекунад, бадани хатогии ҳар формати API-ро нишон медиҳад ва мегӯяд, ки кадом хатогиҳо сазовори такрор мебошанд.
SDK-ҳо объекти хатогӣ медиҳанд, ки рамзи ҳолат ва майдонҳои баданро дорад. Ин дархост номи модели мавҷуд набударо дорад:
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"}]
}' Он ҳолати 400 ва ин баданро бармегардонад:
{
"error": {
"type": "invalid_request_error",
"message": "unknown model: no-such-model"
}
} Бадани хатогӣ
Ду бадан вуҷуд дорад. /v1/messages дар формати Anthropic ҷавоб медиҳад; ҳар endpoint-и дигар дар формати OpenAI ҷавоб медиҳад. Дар ҳарду тафсилот дар error.type ва error.message аст, бинобар ин як хонанда ба ҳамаи endpoint-ҳо хизмат мекунад.
{
"error": {
"type": "authentication_error",
"message": "Invalid API key",
"code": "invalid_api_key",
"param": null
}
} {
"type": "error",
"error": {
"type": "authentication_error",
"message": "Invalid API key"
}
} | Майдон | Навъ | Тавсиф |
|---|---|---|
error.type | string | Навъи хатогӣ. Поёнтар Навъҳои хатогиро бинед. |
error.message | string | Ҷумла барои одам. Матнҳои ҷадвалҳои поён то қисматҳои тағйирёбандаашон, ки ҳамчун <id>, <n> ё … нишон дода шудаанд, собит мебошанд. |
error.code | string | null | Дар баъзе хатогиҳои формати OpenAI ҳозир аст: invalid_api_key бо 401, request_too_large бо 413, context_length_exceeded вақте ки гуфтугӯ аз ҳад дароз аст, дар ҳолати дигар null ё ғоиб. Аввал аз рӯи ҳолат ва error.type қарор диҳед ва code-ро ҳамчун иловагӣ баррасӣ кунед. |
error.param | null | Дар ҳамон хатогиҳое ҳозир аст, ки code. Ҳамеша null. |
type | string | Танҳо формати Anthropic. Ҳамеша error. |
Навъҳои хатогӣ
| Навъ | Ҳолатҳо | Тавсиф |
|---|---|---|
invalid_request_error | 400, 413, 415, 422 | Худи дархост нодуруст аст: майдон, бадан, id-и модел ё вурудие, ки модел қабул намекунад. Пеш аз бори дигар фиристодан дархостро тағйир диҳед. |
authentication_error | 401 | Калиди API намерасад, ношинос аст ё бекор шудааст. |
not_found_error | 404 | Роҳ вуҷуд надорад. |
rate_limit_error | 429 | Баланс дархостро фаро намегирад, ҳифз аз дархостҳои аз ҳад зиёд онро боздошт, ё модел банд аст. Паём мегӯяд, ки кадом. |
api_error | 500, 502, 503, 504 | Дархост дуруст буд ва нокомӣ аз тарафи мост. Онро бори дигар фиристед. |
server_error | 500 | Дархост дуруст буд ва нокомӣ аз тарафи мост. Онро бори дигар фиристед. |
Рамзҳои ҳолат
| Ҳолат | Навъ | Паём | Кай |
|---|---|---|---|
400 | invalid_request_error | Failed to parse the request body as JSON: … | Бадан JSON-и дуруст нест. |
400 | invalid_request_error | unknown model: <id> | model id-и нашршуда нест. Дар /v1/responses ҳамчунин вақте ки model намерасад. |
400 | invalid_request_error | No user message provided | Сатҳҳои Shannon: дархост матни корбар надорад. |
400 | invalid_request_error | <id> does not accept image input | Тасвир ба модели open-weight-и хостшуда фиристода шуд, ки вуруди тасвирро надорад. |
400 | invalid_request_error | audio and video input are not supported by any hosted model | Қисми аудио ё видео ба модели open-weight-и хостшуда фиристода шуд. |
400 | invalid_request_error | <id> does not accept response_format | Баромади сохторӣ аз модели open-weight-и хостшуда, ки онро надорад, дархост шуд. |
400 | invalid_request_error | <id> does not accept response_format json_schema; use json_object | JSON schema ба модели open-weight-и хостшуда фиристода шуд, ки танҳо json_object-ро қабул мекунад. |
400 | invalid_request_error | unknown reasoning effort '<value>'; expected off, low, medium or high | Сатҳи кӯшиши reasoning яке аз қиматҳои номбаршуда нест. Моделҳои open-weight-и хостшуда. |
400 | invalid_request_error | count_tokens is available for the hosted open models; unknown model: <id> | Ҳисоби токен барои модели берун аз моделҳои open-weight-и хостшуда дархост шуд. |
401 | authentication_error | Missing authentication | Калиди API фиристода нашуд. |
401 | authentication_error | Invalid API key | Калид ношинос аст, бо калиди навтар иваз шудааст ё бекор шудааст. |
404 | not_found_error | Not Found | Роҳ вуҷуд надорад, масалан /v1/embeddings. |
405 | api_error | Method Not Allowed | Роҳ вуҷуд дорад, аммо на бо ин усули HTTP. |
413 | invalid_request_error | Failed to buffer the request body: … | Бадани дархост аз 32 MiB калонтар аст. |
415 | invalid_request_error | Expected request with `Content-Type: application/json` | Сарлавҳаи Content-Type намерасад ё application/json нест. |
422 | invalid_request_error | Failed to deserialize the JSON body into the target type: … | Майдони ҳатмӣ намерасад, масалан messages, ё майдоне навъи JSON-и нодуруст дорад. |
429 | rate_limit_error | Quota exceeded. Upgrade your plan at shannon-ai.com/plan | Ҳадди баромади дархост аз боқимондаи балансатон калонтар аст. |
429 | rate_limit_error | Too many requests. Retry in <n>s. | Ҳифз аз дархостҳои аз ҳад зиёд: беш аз 120 дархост дар як дақиқа дар аккаунти шумо. <n> шумораи сонияҳо то анҷоми дақиқа аст. |
429 | rate_limit_error | Shannon Coder call quota reached. Upgrade your plan at shannon-ai.com/plan | shannon-coder-1 дар /v1/chat/completions ва /v1/messages: даъватҳои Shannon Coder-и нақшаи шумо барои равзанаи 4-соатаи ҷорӣ истифода шудаанд. |
429 | rate_limit_error | Shannon routes are temporarily busy. Please retry. | Модел дар ин лаҳза банд аст. |
500 | server_error | The model backend failed to answer. Please retry. | Модел ҷавоб насохт. |
500 | server_error | An internal error occurred. Please retry. | Нокомии дохилӣ ҳангоми омода кардани дархост. |
502 | api_error | The model backend failed to answer. Please retry. | Модел ҷавоб насохт. Оилаи Shannon 3 ва моделҳои open-weight-и хостшуда. |
503 | api_error | Could not verify your quota right now. Please retry. | Балансатонро дар ин лаҳза хондан мумкин набуд. |
503 | api_error | token counting is temporarily unavailable for this model | Ҳисоби токен барои ин модел дар ин лаҳза дастрас нест. |
504 | api_error | upstream timed out | Модели open-weight-и хостшуда аз маҳдудияти вақти дархости бе streaming бештар вақт гирифт. |
Санҷишҳо бо ин тартиб иҷро мешаванд: калиди API, бадани дархост, id-и модел, ҳифз аз дархостҳои аз ҳад зиёд, баланс. Бинобар ин дархост бо калиди нодуруст ва бадани нодуруст 401 бармегардонад. Дархосте, ки бо ҳолати 4xx рад карда мешавад, ҳисоб карда намешавад.
Баланс ва ҳифз аз дархостҳои аз ҳад зиёд
Ҳар дархост баробар хидмат карда мешавад: сатҳҳои меъёр ва квотаи алоҳидаи API вуҷуд надорад. Ду чиз ҳамоно метавонанд 429 ҷавоб диҳанд, ҳарду бо навъи rate_limit_error. Паём онҳоро аз ҳам фарқ мекунад.
Баланс
Балансатон меъёри ҳаррӯзаи нақша аст, ки соати 00:00 UTC аз нав оғоз мешавад, ва пас аз он кредити харидашудаатон. Чат ва API аз ҳамон як баланс сарф мекунанд.
Ҳар дархост аввал ҳадди баромади худро ҷудо мекунад: max_tokens, ё max_output_tokens дар /v1/responses, 4,096 вақте ки ҳеҷ яке фиристода нашудааст. Вақте ки ҷавоб тамом мешавад, миқдори ҷудошуда бо он чи дархост истифода кард, иваз карда мешавад. Агар миқдор ба балансе, ки мондааст, ҷо нашавад, дархост пеш аз оғози модел Quota exceeded бармегардонад.
Дархостҳое, ки ҳамзамон иҷро мешаванд, ҳар кадом миқдори худро ҷудо мекунанд. Бинобар ин бисёр дархостҳои мувозӣ бо max_tokens-и баланд метавонанд балансро лаҳзае тамом кунанд, ҳатто агар ҳар ҷавоб кӯтоҳ бошад. max_tokens-и камтар камтар ҷудо мекунад.
Ҳифз аз дархостҳои аз ҳад зиёд
Ҳифз аз дархостҳои аз ҳад зиёд 120 дархост дар як дақиқа барои ҳар аккаунтро иҷозат медиҳад. Он аккаунтро ҳисоб мекунад, на калидро, дар /v1/chat/completions, /v1/responses ва /v1/messages якҷоя. Дақиқа бо аввалин дархости шумо оғоз мешавад.
Дархости рақами 121 дар дохили он дақиқа Too many requests. Retry in <n>s. бармегардонад ва ҳеҷ арзише надорад. Дархостҳои рад кардашуда низ ҳисоб мешаванд, бинобар ин клиенте, ки бе интизорӣ бори дигар мефиристад, то анҷоми дақиқа рад шуда мемонад. <n> сонияро аз паём интизор шавед.
Дархостҳое, ки мувозӣ фиристода мешаванд, барои мувозӣ будан рад карда намешаванд. Онҳо дар навбат меистанд ва ба навбат ҷавоб дода мешаванд.
GET /v1/models ва endpoint-ҳои ҳисоби токен ҳисоб карда намешаванд.
Бештар дар бораи маҳдудиятҳо ва баланс ва ин ки балансу истифодаи худро дар куҷо дидан мумкин аст: Маҳдудиятҳо ва баланс Калидҳо ва истифода
Чиро такрор кардан лозим
Дархостро танҳо вақте бори дигар фиристед, ки ҳамон дархост муваффақ шуда метавонад. SDK-ҳои OpenAI ва Anthropic ҷавобҳои 429 ва 5xx-ро аллакай худашон ду бор такрор мекунанд; барои тағйир додани ин max_retries-ро (maxRetries дар JavaScript) муқаррар кунед.
| Хатогӣ | Бори дигар фиристем? | Чӣ тавр |
|---|---|---|
400, 404, 405, 413, 415, 422 | Не. Аввал дархостро ислоҳ кунед. | Паём майдон, модел ё вурудеро, ки нодуруст аст, номбар мекунад. |
401 | Не. Калиди дуруст истифода баред. | Калидро дар саҳифаи Калидҳо ва истифода созед ё иваз кунед. |
429 Too many requests | Ҳа, пас аз интизорӣ. | Шумораи сонияҳои дар паём бударо интизор шавед, баъд ҳамон дархостро фиристед. |
429 Quota exceeded | Бо ҳамин ҳол не. | max_tokens-ро кам кунед, барқароршавии ҳаррӯзаро соати 00:00 UTC интизор шавед, ё кредит илова кунед. |
429 Shannon Coder call quota reached | Ҳа, дар равзанаи навбатӣ. | Равзанаҳо ҳар 4 соат аз 00:00 UTC оғоз мешаванд. Модели дигар фавран ҷавоб медиҳад. |
429 … temporarily busy | Ҳа. | Чанд сония интизор шавед, баъд дар ҳар кӯшиши минбаъда дарозтар. |
500, 502, 503 | Ҳа. | 1 сония интизор шавед, баъд 2, 4 ва 8. Пас аз чанд кӯшиш бас кунед ва id-и дархостро хабар диҳед. |
504 | Ҳа. | Онро бо stream, ки ба true гузошта шудааст, фиристед: маҳдудияти вақт ба ҷавобҳои бе streaming татбиқ мешавад. |
Ҳалқаи такрор, ки ин ҷадвалро пайравӣ мекунад:
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); Хатогиҳо дар дохили ҷараён
Ҷараён аз аввалин байти худ ҳолати 200 дорад. Нокомӣ пас аз он ҳамчун рӯйдод дар дохили ҷараён меояд: чанк бо узви error дар /v1/chat/completions, рӯйдоди error дар /v1/messages, рӯйдоди response.failed ё error дар /v1/responses. Рӯйдодҳои анҷомдиҳандаи ҷараён ҳамоно пайравӣ мекунанд. Чунин ҷавобро ноком ҳисоб кунед ва дархостро бори дигар фиристед, мисли ҳолати 5xx.
Гуфтугӯе, ки аз равзанаи контексти модел дарозтар аст, ҳамин тавр хабар дода мешавад, бо навъи invalid_request_error ва рамзи context_length_exceeded. Гуфтугӯро пеш аз бори дигар фиристодан кӯтоҳ кунед.
Фреймҳои дақиқ бо streaming тавсиф шудаанд. Стриминг
Id-ҳои дархост
Ҳар ҷавоб, аз ҷумла хатогиҳо, сарлавҳаи x-request-id дорад. Он қимати дар сарлавҳаи x-request-id-и худатон фиристодаатон аст, ё 12 аломати шонздаҳӣ вақте ки чизе нафиристодед. Онро сабт кунед ва ҳангоми дархости кӯмак дар бораи дархост қайд кунед.