مواد پر جائیں
غلطیاں

غلطیاں

جو درخواست ناکام ہو وہ 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

یہ اسٹیٹس 400 اور یہ باڈی لوٹاتی ہے:

400 JSON
{
  "error": {
    "type": "invalid_request_error",
    "message": "unknown model: no-such-model"
  }
}

ایرر باڈی

دو باڈیز ہیں۔ /v1/messages Anthropic فارمیٹ میں جواب دیتا ہے؛ باقی ہر endpoint OpenAI فارمیٹ میں۔ دونوں میں تفصیل error.type اور error.message میں ہے، اس لیے ایک ہی ریڈر تمام endpoints کے لیے کافی ہے۔

401 OpenAI فارمیٹ
{
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key",
    "code": "invalid_api_key",
    "param": null
  }
}
401 Anthropic فارمیٹ
{
  "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)

سٹریم کے اندر ایررز

سٹریم کا اسٹیٹس پہلے بائٹ سے 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 ہیکسا ڈیسیمل حروف اگر آپ نے کچھ نہ بھیجا ہو۔ اسے لاگ کریں، اور کسی درخواست کے بارے میں مدد مانگتے وقت اس کا حوالہ دیں۔