कंटेंट पर जाएँ
त्रुटि प्रबंधन

त्रुटि प्रबंधन

विफल होने वाला अनुरोध एक 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

यह स्टेटस 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 key गायब है, अज्ञात है या रद्द की जा चुकी है।
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 schema भेजा गया।
400 invalid_request_error unknown reasoning effort '<value>'; expected off, low, medium or high रीज़निंग effort सूचीबद्ध मानों में से नहीं है। होस्टेड ओपन-वेट मॉडल।
400 invalid_request_error count_tokens is available for the hosted open models; unknown model: <id> होस्टेड ओपन-वेट मॉडल से बाहर के किसी मॉडल के लिए टोकन गिनती माँगी गई।
401 authentication_error Missing authentication कोई API key नहीं भेजी गई।
401 authentication_error Invalid API key Key अज्ञात है, नई 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 key, अनुरोध बॉडी, मॉडल id, flood protection, बैलेंस। इसलिए गलत key और गलत बॉडी वाला अनुरोध 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 को मिलाकर अकाउंट की गिनती करता है, key की नहीं। मिनट आपके पहले अनुरोध से शुरू होता है।

उस मिनट के भीतर 121वाँ अनुरोध Too many requests. Retry in <n>s. लौटाता है और उसकी कोई लागत नहीं होती। अस्वीकृत अनुरोध भी गिने जाते हैं, इसलिए बिना रुके फिर से भेजने वाला क्लाइंट मिनट खत्म होने तक अस्वीकृत रहता है। संदेश में दिए <n> सेकंड प्रतीक्षा करें।

समानांतर भेजे गए अनुरोध समानांतर होने के कारण अस्वीकार नहीं होते। वे कतार में इंतज़ार करते हैं और बारी-बारी से उत्तर पाते हैं।

GET /v1/models और टोकन गिनने वाले endpoints नहीं गिने जाते।

सीमाओं और बैलेंस के बारे में और, और अपना बैलेंस व उपयोग कहाँ देखें: सीमाएँ और बैलेंस Keys और उपयोग

क्या दोबारा आज़माना है

अनुरोध तभी फिर से भेजें जब वही अनुरोध सफल हो सकता हो। OpenAI और Anthropic SDK 429 और 5xx उत्तरों को पहले से अपने आप दो बार दोबारा आज़माते हैं; इसे बदलने के लिए max_retries (JavaScript में maxRetries) सेट करें।

त्रुटि फिर से भेजें? कैसे
400, 404, 405, 413, 415, 422 नहीं। पहले अनुरोध सुधारें। संदेश उस फ़ील्ड, मॉडल या इनपुट का नाम बताता है जो गलत है।
401 नहीं। वैध key उपयोग करें। Keys & usage पेज पर key बनाएँ या बदलें।
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)

स्ट्रीम के भीतर की त्रुटियाँ

स्ट्रीम का स्टेटस पहले बाइट से 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 हेक्साडेसिमल अक्षर। इसे लॉग करें, और अनुरोध के बारे में मदद माँगते समय इसे उद्धृत करें।