د تېروتنې اداره کول
هغه غوښتنه چې ناکامه شي HTTP د حالت کوډ او د JSON بدنه د تېروتنې ډول او پیغام سره بیرته ورکوي. دا پاڼه هر حالت لیست کوي، د هر API بڼې د تېروتنې بدنه ښيي او وايي چې کومې تېروتنې د بیا لیږلو ارزښت لري.
SDKs د تېروتنې څیز راپورته کوي چې د حالت کوډ او د بدنې ساحې لري. دا غوښتنه هغه ماډل نوموي چې نشته:
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 کې دي، نو یو لوستونکی ټولو endpoints ته کافي دی.
{
"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 یا هغه input چې ماډل یې نه مني. مخکې له بیا لیږلو غوښتنه بدله کړئ. |
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 | انځور هغه کوربه شوي 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 د هغه کوربه شوي 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 effort د لیست شوو ارزښتونو څخه نه دی. کوربه شوي 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 header نشته یا 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 کې: ستاسو د پلان د اوسنۍ 4 ساعتې کړکۍ Shannon Coder calls کارول شوي. |
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 کیلي، د غوښتنې بدنه، د ماډل id، flood protection، بیلانس. هغه غوښتنه چې غلطه کیلي او غلطه بدنه لري نو 401 بیرته ورکوي. هغه غوښتنه چې د 4xx حالت سره رد شي بیل نه کیږي.
بیلانس او flood protection
هره غوښتنه برابره خدمت کیږي: هیڅ rate کچې نشته او هیڅ جلا API کوټه نشته. دوه شیان بیا هم کولی شي 429 ځواب کړي، دواړه د rate_limit_error ډول سره. پیغام یې سره جلا کوي.
بیلانس
ستاسو بیلانس د نن ورځې د پلان اجازه ده، چې په 00:00 UTC بیا ټاکل کیږي، او وروسته له هغې ستاسو اخیستل شوی کریډیټ. چیټ او API له هماغه بیلانس اخلي.
هره غوښتنه لومړی خپل د output حد ساتي: 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 او د ټوکنونو شمېرنې endpoints نه شمیرل کیږي.
د حدونو او بیلانس په اړه نور، او هغه ځای چیرته چې خپل بیلانس او usage وګورئ: حدونه او بیلانس کیلي او کارونه
څه بیا هڅه کول
غوښتنه یوازې هغه وخت بیا ولیږئ کله چې هماغه غوښتنه بریالۍ کیدی شي. OpenAI او Anthropic SDKs لا دمخه 429 او 5xx ځوابونه دوه ځله پخپله بیا هڅه کوي؛ د بدلولو لپاره max_retries (په JavaScript کې maxRetries) وټاکئ.
| تېروتنه | بیا لیږل؟ | څنګه |
|---|---|---|
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 نه وي. |
د بیا هڅې loop چې دا جدول تعقیبوي:
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 له لومړي بایټ څخه حالت 200 لري. له هغې وروسته ناکامي د stream دننه د رخداد په توګه رارسیږي: په /v1/chat/completions کې د error غړي سره chunk، په /v1/messages کې error رخداد، په /v1/responses کې response.failed یا error رخداد. د stream بندیدو رخدادونه بیا هم ورپسې راځي. داسې ځواب ناکام وګڼئ او غوښتنه بیا ولیږئ، لکه د 5xx حالت لپاره.
ګفتګه چې د ماډل له context window څخه اوږده وي پدې ډول راپور کیږي، د ډول invalid_request_error او کوډ context_length_exceeded سره. ګفتګه مخکې له بیا لیږلو لنډه کړئ.
دقیق frames د streaming سره بیان شوي. جریان
د غوښتنې id ګانې
هر ځواب، تېروتنې په ګډون، x-request-id header لري. دا هغه ارزښت دی چې تاسو په خپل x-request-id header کې لیږلی، یا 12 هیکساډیسیمل توري کله چې تاسو هیڅ نه وي لیږلی. دا ثبت کړئ، او کله چې د غوښتنې په اړه مرسته غواړئ یادونه یې وکړئ.