Ката иштетүү
Ишке ашпаган сурам 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 | Сүрөт кириши жок хостингдеги ачык салмактуу моделге сүрөт жөнөтүлдү. |
400 | invalid_request_error | audio and video input are not supported by any hosted model | Хостингдеги ачык салмактуу моделге аудио же видео бөлүгү жөнөтүлдү. |
400 | invalid_request_error | <id> does not accept response_format | Структураланган чыгыш аны колдобогон хостингдеги ачык салмактуу моделден суралды. |
400 | invalid_request_error | <id> does not accept response_format json_schema; use json_object | json_object гана кабыл алган хостингдеги ачык салмактуу моделге JSON схемасы жөнөтүлдү. |
400 | invalid_request_error | unknown reasoning effort '<value>'; expected off, low, medium or high | Reasoning аракети тизмектеги маанилердин бири эмес. Хостингдеги ачык салмактуу моделдер. |
400 | invalid_request_error | count_tokens is available for the hosted open models; unknown model: <id> | Токен саноо хостингдеги ачык салмактуу моделдерден тышкаркы модель үчүн суралган. |
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 үй-бүлөсү жана хостингдеги ачык салмактуу моделдер. |
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 | Хостингдеги ачык салмактуу модель стримдебеген сурамдын убакыт чегинен узагыраак убакыт алды. |
Текшерүүлөр ушул тартипте жүрөт: 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'тери эсептелбейт.
Чектөөлөр жана баланс жөнүндө көбүрөөк, ошондой эле өз балансыңыз менен колдонууңузду кайдан көрүүгө болору: Чектөөлөр жана баланс Ачкычтар жана колдонуу
Эмнени кайра жөнөтүү керек
Сурамды ошол эле сурам ийгиликтүү болуши мүмкүн болгондо гана кайра жөнөтүңүз. 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. Кайра жөнөтүүдөн мурун сүйлөшүүнү кыскартыңыз.
Так фреймдер стриминг бетинде сүрөттөлгөн. Стриминг
Сурам id'лери
Ар бир жооп, каталар да, x-request-id башына ээ. Бул сиз өз x-request-id башыңызда жөнөткөн маани, же эч нерсе жөнөтпөсөңүз 12 он алтылык белги. Аны журналга жазыңыз жана сурам боюнча жардам сурасаңыз көрсөтүңүз.