त्रुटि प्रबंधन
विफल होने वाला अनुरोध एक 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 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 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) 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 सदस्य वाला चंक, /v1/messages पर error इवेंट, /v1/responses पर response.failed या error इवेंट। स्ट्रीम के समापन इवेंट फिर भी आते हैं। ऐसे उत्तर को विफल मानें और 5xx स्टेटस की तरह अनुरोध फिर से भेजें।
मॉडल की कॉन्टेक्स्ट विंडो से लंबी बातचीत इसी तरह बताई जाती है, प्रकार invalid_request_error और कोड context_length_exceeded के साथ। फिर से भेजने से पहले बातचीत छोटी करें।
सटीक फ़्रेम स्ट्रीमिंग के साथ बताए गए हैं। स्ट्रीमिंग
रिक्वेस्ट id
हर उत्तर में, त्रुटियों सहित, एक x-request-id हेडर होता है। यह वह मान है जो आपने अपने x-request-id हेडर में भेजा था, या कुछ न भेजने पर 12 हेक्साडेसिमल अक्षर। इसे लॉग करें, और अनुरोध के बारे में मदद माँगते समय इसे उद्धृत करें।