Қателерді өңдеу
Сәтсіз аяқталған сұрау 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 форматының кейбір қателерінде болады: 401 кезінде invalid_api_key, 413 кезінде request_too_large, сөйлесу тым ұзын болғанда 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 | Баланс сұранысты жаппайды, flood protection оны тоқтатты немесе модель бос емес. Қайсысы екенін хабарлама айтады. |
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 | Сурет кірісі жоқ hosted open-weight модельге сурет жіберілді. |
400 | invalid_request_error | audio and video input are not supported by any hosted model | Hosted open-weight модельге аудио немесе бейне бөлігі жіберілді. |
400 | invalid_request_error | <id> does not accept response_format | Құрылымдалған шығыс оны қолдамайтын hosted open-weight модельден сұралды. |
400 | invalid_request_error | <id> does not accept response_format json_schema; use json_object | Тек json_object қабылдайтын hosted open-weight модельге JSON схемасы жіберілді. |
400 | invalid_request_error | unknown reasoning effort '<value>'; expected off, low, medium or high | Пайымдау күші тізімдегі мәндердің бірі емес. Hosted open-weight модельдер. |
400 | invalid_request_error | count_tokens is available for the hosted open models; unknown model: <id> | Токен санау hosted 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. | Flood protection: аккаунтыңызда бір минутта 120-дан астам сұрау. <n> — минут біткенге дейінгі секунд саны. |
429 | rate_limit_error | Shannon Coder call quota reached. Upgrade your plan at shannon-ai.com/plan | /v1/chat/completions және /v1/messages бойынша shannon-coder-1: жоспарыңыздың ағымдағы 4 сағаттық терезедегі Shannon Coder шақырулары таусылды. |
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 отбасы және hosted 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 | Hosted open-weight модель стримсіз сұрау уақыт шегінен ұзақ уақыт алды. |
Тексерулер мына ретпен орындалады: API кілті, сұрау денесі, модель id-і, flood protection, баланс. Сондықтан қате кілті және қате денесі бар сұрау 401 қайтарады. 4xx мәртебесімен қабылданбаған сұрау үшін ақы алынбайды.
Баланс және flood protection
Әр сұрау тең қызмет көрсетіледі: жиілік деңгейлері де, жеке API квотасы да жоқ. Дегенмен екі жағдай 429 қайтара алады, екеуі де rate_limit_error түрімен. Оларды хабарлама ажыратады.
Баланс
Балансыңыз — 00:00 UTC уақытында жаңаратын бүгінгі жоспар лимиті, ал одан кейін сатып алынған кредит. Чат пен API бір балансты пайдаланады.
Әр сұрау алдымен өзінің шығыс шегін бөлек сақтайды: max_tokens, немесе /v1/responses бойынша max_output_tokens, екеуін де жібермесеңіз 4,096. Жауап толық болғанда бөлек сақталған сома сұраудың жұмсағанымен ауыстырылады. Сома қалған балансқа сыймаса, сұрау модель басталмай тұрып Quota exceeded қайтарады.
Бір мезгілде орындалатын сұраулар әрқайсысы өз сомасын бөлек сақтайды. Сондықтан жоғары max_tokens бар көп параллель сұрау әр жауап қысқа болса да, балансты біраз уақытқа таусуы мүмкін. Төменірек max_tokens азырақ бөлек сақтайды.
Flood protection
Flood protection аккаунтқа минутына 120 сұрауға рұқсат береді. Ол /v1/chat/completions, /v1/responses және /v1/messages бойынша кілтті емес, аккаунтты бірге санайды. Минут алғашқы сұрауыңыздан басталады.
Сол минуттағы 121-сұрау Too many requests. Retry in <n>s. қайтарады және ештеңе тұрмайды. Бас тартылған сұраулар да есептеледі, сондықтан күтпей қайта жіберетін клиент минут біткенше бас тартуды алып отырады. Хабарламадағы <n> секундты күтіңіз.
Параллель жіберілген сұраулар параллель болғаны үшін қабылданбай қалмайды. Олар кезекте тұрып, ретімен жауап алады.
GET /v1/models және токен санау endpoint-тері есептелмейді.
Шектеулер мен баланс туралы толығырақ және өз балансыңыз бен қолдануыңызды қайдан көру керек: Шектеулер және баланс Keys & usage
Нені қайталау керек
Сұрауды тек сол сұрау сәтті болуы мүмкін болғанда ғана қайта жіберіңіз. OpenAI және Anthropic SDK-лары 429 және 5xx жауаптарын өздері екі рет қайталайды; оны өзгерту үшін max_retries (JavaScript-те maxRetries) орнатыңыз.
| Қате | Қайта жіберу керек пе? | Қалай |
|---|---|---|
400, 404, 405, 413, 415, 422 | Жоқ. Алдымен сұрауды түзетіңіз. | Хабарлама қате өрісті, модельді немесе кірісті атайды. |
401 | Жоқ. Жарамды кілтті қолданыңыз. | Кілтті Keys & usage бетінде жасаңыз немесе ауыстырыңыз. |
429 Too many requests | Иә, күткеннен кейін. | Хабарламадағы секунд санын күтіңіз, содан кейін сол сұрауды жіберіңіз. |
429 Quota exceeded | Қазіргідей емес. | max_tokens мәнін төмендетіңіз, 00:00 UTC уақытындағы күнделікті жаңартуды күтіңіз немесе кредит қосыңыз. |
429 Shannon Coder call quota reached | Иә, келесі терезеде. | Терезелер 00:00 UTC-тен бастап әр 4 сағат сайын басталады. Басқа модель бірден жауап береді. |
429 … temporarily busy | Иә. | Бірнеше секунд күтіңіз, одан кейінгі әр әрекетте ұзағырақ. |
500, 502, 503 | Иә. | 1 секунд күтіңіз, содан кейін 2, 4 және 8. Бірнеше әрекеттен кейін тоқтап, сұрау id-ін хабарлаңыз. |
504 | Иә. | Оны stream мәні true етіп жіберіңіз: уақыт шегі стримсіз жауаптарға қолданылады. |
Осы кестені ұстанатын қайталау циклі:
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. Одан кейінгі ақау стрим ішіндегі оқиға ретінде келеді: /v1/chat/completions бойынша error мүшесі бар бөлік, /v1/messages бойынша error оқиғасы, /v1/responses бойынша response.failed немесе error оқиғасы. Стримнің жабушы оқиғалары бәрібір артынан келеді. Мұндай жауапты сәтсіз деп санап, 5xx мәртебесіндегідей сұрауды қайта жіберіңіз.
Модельдің контекст терезесінен ұзын сөйлесу осылай хабарланады, invalid_request_error түрімен және context_length_exceeded кодымен. Қайта жібермес бұрын сөйлесуді қысқартыңыз.
Нақты кадрлар streaming бөлімінде сипатталған. Стриминг
Сұрау id-лері
Әр жауапта, қателерді қоса, x-request-id тақырыбы бар. Ол өз x-request-id тақырыбыңызда жіберген мән, ал ештеңе жібермесеңіз 12 оналтылық таңба. Оны журналға жазыңыз және сұрау бойынша көмек сұрағанда келтіріңіз.