غلطیاں
جو درخواست ناکام ہو وہ HTTP اسٹیٹس کوڈ اور ایرر type اور پیغام والی 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 یا ایسا ان پٹ جو ماڈل نہیں لیتا۔ دوبارہ بھیجنے سے پہلے درخواست بدلیں۔ |
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 اسکیما بھیجا گیا جو صرف json_object لیتا ہے۔ |
400 | invalid_request_error | unknown reasoning effort '<value>'; expected off, low, medium or high | reasoning effort درج شدہ قدروں میں سے نہیں ہے۔ ہوسٹڈ اوپن ویٹ ماڈلز۔ |
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 سے جواب دے سکتی ہیں، دونوں type 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 اور ٹوکن گنتی والے endpoints شمار نہیں ہوتے۔
حدود اور بیلنس کے بارے میں مزید، اور اپنا بیلنس اور استعمال کہاں دیکھیں: حدود اور بیلنس Keys & usage
کن پر دوبارہ کوشش کریں
درخواست صرف تب دوبارہ بھیجیں جب وہی درخواست کامیاب ہو سکتی ہو۔ OpenAI اور Anthropic SDKs 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 پر سیٹ کر کے بھیجیں: وقت کی حد ان جوابات پر لاگو ہوتی ہے جو سٹریم نہیں ہوتے۔ |
اس جدول کی پیروی کرنے والا retry لوپ:
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 رکن والا chunk، /v1/messages پر error ایونٹ، /v1/responses پر response.failed یا error ایونٹ۔ سٹریم کے اختتامی ایونٹس پھر بھی آتے ہیں۔ ایسے جواب کو ناکام سمجھیں اور درخواست دوبارہ بھیجیں، جیسے 5xx اسٹیٹس پر۔
ماڈل کی کانٹیکسٹ ونڈو سے لمبی گفتگو اسی طرح رپورٹ ہوتی ہے، type invalid_request_error اور code context_length_exceeded کے ساتھ۔ دوبارہ بھیجنے سے پہلے گفتگو مختصر کریں۔
درست فریمز کی وضاحت سٹریمنگ کے ساتھ ہے۔ اسٹریمنگ
درخواست کے ids
ہر جواب، ایررز سمیت، میں x-request-id ہیڈر ہوتا ہے۔ یہ وہ قدر ہے جو آپ نے اپنے x-request-id ہیڈر میں بھیجی، یا 12 ہیکسا ڈیسیمل حروف اگر آپ نے کچھ نہ بھیجا ہو۔ اسے لاگ کریں، اور کسی درخواست کے بارے میں مدد مانگتے وقت اس کا حوالہ دیں۔