Çewtî
داواکارییەکی شکستخواردوو کۆدی status ی HTTP و body ی JSON ێک دەگەڕێنێتەوە کە جۆری هەڵە و پەیامی تێدایە. ئەم لاپەڕەیە هەموو status ـەکان لیست دەکات، body ی هەڵەی هەر فۆرماتێکی API نیشان دەدات و دەڵێت کام هەڵە ئەوەندە بەهادارن کە دووبارە بنێردرێنەوە.
SDK ـەکان ئۆبجێکتێکی هەڵە دەهێنن کە کۆدی status و بوارەکانی body هەڵدەگرێت. ئەم داواکارییە ناوی مۆدێلێک دەبات کە بوونی نییە:
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"}]
}' status ی 400 و ئەم body ە دەگەڕێنێتەوە:
{
"error": {
"type": "invalid_request_error",
"message": "unknown model: no-such-model"
}
} جەستەی هەڵە
دوو body هەیە. /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 یان نەبوو. سەرەتا بەپێی status و error.type بڕیار بدە و code وەک زیادەیەک مامەڵە لەگەڵ بکە. |
error.param | null | لەسەر هەمان هەڵەکانی code هەیە. هەمیشە null. |
type | string | تەنها فۆرماتی Anthropic. هەمیشە error. |
جۆرەکانی هەڵە
| جۆر | Statusـەکان | وەسف |
|---|---|---|
invalid_request_error | 400, 413, 415, 422 | خودی داواکارییەکە هەڵەیە: بوارێک، body، id ی مۆدێل یان input ێک کە مۆدێلەکە وەری ناگرێت. داواکارییەکە بگۆڕە پێش ئەوەی دووبارە بینێریت. |
authentication_error | 401 | کلیلی API نییە، نەناسراوە یان هەڵوەشێنراوەتەوە. |
not_found_error | 404 | ڕێگاکە بوونی نییە. |
rate_limit_error | 429 | باڵانس داواکارییەکە ناگرێتەوە، flood protection ڕایگرت، یان مۆدێلەکە ماندووە. پەیامەکە دەڵێت کامیان. |
api_error | 500, 502, 503, 504 | داواکارییەکە دروست بوو و شکستەکە لە لای ئێمەیە. دووبارە بینێرە. |
server_error | 500 | داواکارییەکە دروست بوو و شکستەکە لە لای ئێمەیە. دووبارە بینێرە. |
کۆدەکانی status
| دۆخ | جۆر | پەیام | کەی |
|---|---|---|---|
400 | invalid_request_error | Failed to parse the request body as JSON: … | body ی 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 ی میوانداریکراو نێردرا کە input ی وێنەی نییە. |
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 | output ی structured لە مۆدێلێکی 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 | ئاستی بیرکردنەوە یەکێک نییە لە بەها لیستکراوەکان. مۆدێلە 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: … | body ی داواکارییەکە لە 32 MiB گەورەترە. |
415 | invalid_request_error | Expected request with `Content-Type: application/json` | header ی 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 | سنووری output ی داواکارییەکە لەوەی لە باڵانسەکەت ماوە گەورەترە. |
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 | 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 ی میوانداریکراو لە سنووری کاتی داواکارییەک کە stream نەکراوە زیاتری خایاند. |
پشکنینەکان بەم ڕیزبەندییە ئەنجام دەدرێن: کلیلی API، body ی داواکاری، id ی مۆدێل، flood protection، باڵانس. بۆیە داواکارییەک بە کلیلی هەڵە و body ی هەڵە 401 دەگەڕێنێتەوە. داواکارییەک کە بە status ی 4xx ڕەت بکرێتەوە نرخ ناگیرێت.
باڵانس و flood protection
هەموو داواکارییەک یەکسان خزمەت دەکرێت: ئاستی ڕێژە و quota ی API ی جیاواز نییە. هێشتا دوو شت دەتوانن بە 429 وەڵام بدەنەوە، هەردووکیان بە جۆری rate_limit_error. پەیامەکە جیایان دەکاتەوە.
باڵانس
باڵانسەکەت ڕێپێدانی پلانی ئەمڕۆیە، کە لە 00:00 UTC دەست پێدەکاتەوە، و دوای ئەوە کرێدیتی کڕدراوەکەت. Chat و API لە هەمان باڵانس دەخۆن.
هەر داواکارییەک سەرەتا سنووری output ی خۆی ڕادەگرێت: max_tokens، یان max_output_tokens لەسەر /v1/responses، 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
چی دووبارە بکرێتەوە
داواکارییەک تەنها کاتێک دووبارە بنێرە کە هەمان داواکاری بتوانێت سەرکەوتوو بێت. SDK ـەکانی OpenAI و Anthropic خۆیان پێشتر وەڵامەکانی 429 و 5xx دوو جار دووبارە دەکەنەوە؛ max_retries (maxRetries لە JavaScript) بگۆڕە بۆ گۆڕینی ئەوە.
| هەڵە | دووبارە بنێرم؟ | چۆن |
|---|---|---|
400, 404, 405, 413, 415, 422 | نەخێر. سەرەتا داواکارییەکە ڕاست بکەرەوە. | پەیامەکە ناوی ئەو بوار، مۆدێل یان input ە دەبات کە هەڵەیە. |
401 | نەخێر. کلیلێکی دروست بەکاربهێنە. | کلیلەکە لە لاپەڕەی Keys & usage دروست بکە یان بیگۆڕە. |
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 بینێرە: سنووری کات تەنها لەسەر ئەو وەڵامانەیە کە stream ناکرێن. |
خولی دووبارەکردنەوە کە ئەم خشتەیە دەگرێتەبەر:
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); هەڵە لەناو stream دا
stream لە یەکەم بایتەوە status ی 200 ی هەیە. شکستێک دوای ئەوە وەک ڕووداوێک لەناو stream دا دێت: chunk ێک بە ئەندامی error لەسەر /v1/chat/completions، ڕووداوی error لەسەر /v1/messages، ڕووداوی response.failed یان error لەسەر /v1/responses. ڕووداوە کۆتاییەکانی stream هێشتا دەگەن. ئەم وەڵامە وەک شکستخواردوو ببینە و داواکارییەکە دووبارە بنێرە، وەک بۆ status ی 5xx.
گفتوگۆیەک کە لە context window ی مۆدێلەکە درێژتر بێت بەم شێوەیە ڕاپۆرت دەکرێت، بە جۆری invalid_request_error و کۆدی context_length_exceeded. گفتوگۆکە کورت بکەرەوە پێش ئەوەی دووبارە بینێریت.
frame ـە وردەکان لەگەڵ streaming باس کراون. Streaming
id ی داواکاری
هەر وەڵامێک، هەڵەکانیش، header ی x-request-id ی هەیە. ئەو بەهایەیە کە لە header ی x-request-id ی خۆتدا ناردووتە، یان 12 پیتی هەژدەیی ئەگەر هیچت نەناردبێت. لۆگی بکە، و کاتێک بۆ داواکارییەک یارمەتی دەخوازیت بینووسە.