API Hop दस्तावेज़

त्रुटि कोड और निदान

प्लेटफ़ॉर्म के सभी त्रुटि कोड देखें, प्रोटोकॉल-विशिष्ट त्रुटियाँ पहचानें, सुरक्षित पुनःप्रयास करें और उपयोगकर्ता तथा AI सहायक के लिए निदान जानकारी जुटाएँ।

पहचानें कि क्या विफल हुआ

वास्तविक HTTP स्थिति, अनुरोध विधि और पथ दर्ज करें। HTTP स्थिति और ऐप त्रुटि कोड अलग परतें बताते हैं; एक को दूसरे की जगह न लें।
कॉल किए प्रोटोकॉल के अनुसार त्रुटि फ़ील्ड पढ़ें। मूल, OpenAI, Claude और Gemini उत्तरों की संरचना एक जैसी नहीं होती।
स्ट्रीमिंग अनुरोधों में त्रुटि इवेंट और पूर्णता स्थिति भी देखें। असिंक्रोनस जॉब में जॉब status देखें। HTTP 200 सफल जनरेशन की गारंटी नहीं है।
अनुरोध सुधारने या पुनःप्रयास तय करने के लिए नीचे की तालिका लें। message व्याख्यात्मक पाठ है, स्थिर enum नहीं; उसके शब्दों पर प्रोग्राम शाखाएँ न बनाएँ।

यह प्लेटफ़ॉर्म ऐप त्रुटि कोड का पूरा enum है। नाम संदर्भ लेबल हैं; उत्तर के code मान संख्याएँ हैं। “सामान्य HTTP” निदान मार्गदर्शन है, हर एंडपॉइंट का निश्चित मानचित्र नहीं। वास्तविक HTTP स्थिति और उत्तर बॉडी इस्तेमाल करें। अपस्ट्रीम से सीधे आया code इस enum का हिस्सा न भी हो सकता है।

संख्यात्मक `code`	नाम	सामान्य HTTP	अर्थ और कार्रवाई
`10000`	`BAD_REQUEST`	`400`	अमान्य अनुरोध प्रारूप, पथ या बुनियादी पैरामीटर। विधि, पथ, JSON सिंटैक्स और पैरामीटर नाम जाँचें।
`10001`	`VALIDATION_ERROR`	`400` / `422`	पैरामीटर सत्यापन विफल। आवश्यक फ़ील्ड, प्रकार, सीमाएँ और पैरामीटर संयोजन जाँचें।
`20000`	`AUTH_ERROR`	`401`	प्रमाणीकरण विफल। API कुंजी की वैधता, समाप्ति और प्रमाणीकरण हेडर प्रारूप जाँचें।
`20001`	`FORBIDDEN`	`403`	पहुँच अस्वीकृत या खाता प्रतिबंधित है। खाते की अनुमतियाँ और संसाधन स्वामित्व जाँचें।
`30000`	`NOT_FOUND`	`404`	पथ, मॉडल या संसाधन मौजूद नहीं। वर्तमान API कुंजी को दिखने वाले संसाधनों से एंडपॉइंट पथ, `model` और जॉब ID मिलाएँ।
`30001`	`CONFLICT`	`409`	कार्रवाई संसाधन की वर्तमान स्थिति से टकराती है। कार्रवाई बदलने से पहले वर्तमान स्थिति पढ़ें; दोहरे सबमिशन से बचें।
`40000`	`INSUFFICIENT_CREDIT`	`402`	अपर्याप्त शेष राशि। दोबारा कॉल से पहले शेष राशि जाँचें और जोड़ें।
`40001`	`RATE_LIMIT`	`429`	अनुरोध बहुत तेज़ आ रहे हैं। अनुरोध दर घटाएँ और पुनःप्रयास में देरी रखें।
`40002`	`CONCURRENCY_LIMIT`	`429`	बहुत अधिक अनुरोध साथ चल रहे हैं। समवर्ती संख्या घटाएँ और मौजूदा अनुरोध पूरे होने दें।
`50000`	`PROVIDER_ERROR`	`502`	अपस्ट्रीम कॉल विफल हुआ या वैध परिणाम नहीं लौटा। सीमित पुनःप्रयास पर विचार से पहले जाँचें परिणाम बना था या नहीं।
`50001`	`SERVICE_UNAVAILABLE`	`503`	सेवा अस्थायी रूप से अनुपलब्ध है। बाद में सीमित पुनःप्रयास करें; विफलता बनी रहे तो निदान जानकारी जुटाएँ।
`50002`	`GATEWAY_TIMEOUT`	`504`	संसाधन में टाइमआउट हुआ। परिणाम अनिश्चित हो सकता है; पुनःप्रयास से पहले जाँचें निष्पादन हुआ था या नहीं।
`50003`	`INTERNAL_ERROR`	`500`	अवर्गीकृत सर्वर त्रुटि हुई। सीमित पुनःप्रयास करें; विफलता बनी रहे तो निदान जानकारी जुटाएँ।

केवल HTTP 429 से दर सीमा और समवर्ती सीमा भरोसेमंद ढंग से अलग नहीं होतीं। स्पष्ट संख्यात्मक त्रुटि कोड मिलने पर ही अंतर करें। मॉडल सूची में मॉडल पहचान जाँचें; model मान अपने-आप न बदलें।

प्रोटोकॉल के अनुसार त्रुटियाँ पढ़ें

नीचे के उदाहरण सामान्य प्लेटफ़ॉर्म-निर्मित संरचनाएँ दिखाते हैं, हर विफलता के लिए गारंटीकृत एक प्रारूप नहीं। प्रमाणीकरण विफलताएँ अलग संसाधन परतों से आ सकती हैं और अपस्ट्रीम से सीधे लौटे उत्तर अपनी संरचना, स्ट्रिंग कोड या प्रकार रख सकते हैं। पार्स करने से पहले वास्तविक उत्तर संरचना पहचानें। अपरिचित हो तो जबरन रूपांतरण के बजाय मूल फ़ील्ड और HTTP स्थिति सुरक्षित रखें।

मूल प्लेटफ़ॉर्म API

आम तौर पर error.code और error.message पढ़ें। requestId अनुपस्थित हो सकता है।

json

{
  "success": false,
  "error": {
    "code": 10000,
    "message": "Bad request"
  },
  "requestId": "req_example"
}

कुछ त्रुटियाँ शीर्ष-स्तरीय code और message इस्तेमाल कर सकती हैं। क्लाइंट इस अंतर को सँभालें और error ऑब्जेक्ट न होने को सफलता का प्रमाण न मानें। पैरामीटर सत्यापन उत्तर में भी संख्यात्मक त्रुटि कोड न हो सकता है। कोड गढ़ने के बजाय अनुपलब्ध कोड को अज्ञात मानें।

OpenAI-संगत API

सामान्य प्लेटफ़ॉर्म-निर्मित त्रुटियों में शीर्ष-स्तरीय code, message और type होते हैं; वे आवश्यक रूप से error में नहीं लिपटे होते।

json

{
  "code": 40000,
  "message": "Insufficient credit",
  "type": "api_error"
}

type प्रोटोकॉल श्रेणी है; इस संरचना में code प्लेटफ़ॉर्म का संख्यात्मक त्रुटि कोड है। केवल api_error से पुनःप्रयास उचित होना तय नहीं होता। अपस्ट्रीम से सीधे आई और स्ट्रीमिंग त्रुटियों में नेस्टेड error हो सकता है; वास्तविक प्रोटोकॉल उत्तर सँभालें। Chat Completions और Responses देखें।

Claude-संगत API

सामान्य संरचना में शीर्ष-स्तरीय type, error होता है; विशिष्ट श्रेणी error.type और विवरण error.message है। इस संरचना में प्लेटफ़ॉर्म का संख्यात्मक code नहीं है। उसे गढ़ें नहीं।

json

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens must be a positive safe integer"
  }
}

प्लेटफ़ॉर्म स्थानीय रूप से नीचे के Claude त्रुटि प्रकार बनाता है। यह सभी अपस्ट्रीम त्रुटि प्रकारों का पूरा enum नहीं है।

`error.type`	स्थानीय HTTP मानचित्र	क्या जाँचें
`invalid_request_error`	`400`	अनुरोध प्रारूप और पैरामीटर जाँचें।
`authentication_error`	`401`	प्रमाणीकरण क्रेडेंशियल जाँचें।
`api_error`	अन्य HTTP स्थितियाँ	सामान्य API त्रुटि; वास्तविक HTTP स्थिति और विवरण देखें। इसमें पुनःप्रयास आवश्यक रूप से संभव नहीं।

Claude Messages देखें।

Gemini-शैली त्रुटियाँ

Gemini-शैली उत्तर मिले तो error.code, error.message और error.status पढ़ें। यहाँ status स्ट्रिंग श्रेणी है, HTTP स्थिति या असिंक्रोनस जॉब स्थिति नहीं।

json

{
  "error": {
    "code": 10000,
    "message": "Bad request",
    "status": "INVALID_ARGUMENT"
  }
}

इस संरचना की प्लेटफ़ॉर्म-निर्मित त्रुटियाँ प्लेटफ़ॉर्म के संख्यात्मक code मान इस्तेमाल करती हैं। स्थानीय स्ट्रिंग status मानचित्र नीचे है; यह सभी अपस्ट्रीम स्थितियों का enum नहीं।

`error.status`	स्थानीय HTTP मानचित्र	क्या जाँचें
`UNAUTHENTICATED`	`401`	प्रमाणीकरण क्रेडेंशियल जाँचें।
`RESOURCE_EXHAUSTED`	`402` / `429`	शेष राशि या उपयोग सीमा जाँचें; केवल स्ट्रिंग से उनका अंतर नहीं होता।
`PERMISSION_DENIED`	`403`	अनुमतियाँ और संसाधन स्वामित्व जाँचें।
`NOT_FOUND`	`404`	पथ, मॉडल या संसाधन जाँचें।
`UNAVAILABLE`	`503`	सेवा अस्थायी रूप से अनुपलब्ध है।
`INTERNAL`	`>= 500`, `503` को छोड़कर	सर्वर त्रुटि; `504` भी यही मान इस्तेमाल करता है।
`INVALID_ARGUMENT`	अन्य HTTP स्थितियाँ	वास्तविक HTTP स्थिति और अनुरोध जाँचें; `409` भी यही मान इस्तेमाल करता है।

503 को प्राथमिकता मिलती है और वह UNAVAILABLE इस्तेमाल करता है, INTERNAL नहीं। अपस्ट्रीम उत्तर में code और status के अर्थ अलग हो सकते हैं। हर Gemini संख्यात्मक कोड पर प्लेटफ़ॉर्म त्रुटि तालिका लागू न करें।

सुरक्षित पुनःप्रयास करें

स्थिति	सुझाई कार्रवाई
`400` / `401` / `402` / `403` / `404` / `409` / `422`	पहले अनुरोध, क्रेडेंशियल, शेष राशि, अनुमतियाँ या संसाधन स्थिति सुधारें। बिना बदला अनुरोध बार-बार न भेजें। API कुंजियाँ केवल हेडर में भेजें, URL क्वेरी पैरामीटर में कभी नहीं।
`429`	दर और समवर्ती संख्या घटाएँ, फिर पुनःप्रयास से पहले प्रतीक्षा करें। केवल पुनःप्रयास बढ़ाने से आम तौर पर थ्रॉटलिंग बिगड़ती है।
`500` / `502` / `503` / `504`	पहले दोहरे निष्पादन का जोखिम आँकें, फिर jitter के साथ सीमित एक्सपोनेंशियल बैकऑफ़ लें, जैसे कुल प्रतीक्षा सीमा के भीतर अधिकतम 3 पुनःप्रयास।
नेटवर्क डिस्कनेक्शन या क्लाइंट टाइमआउट	परिणाम न मिलने का अर्थ सर्वर ने अनुरोध नहीं चलाया होना नहीं। विफलता घोषित करने या तुरंत दूसरा अनुरोध बनाने के बजाय परिणाम अज्ञात चिह्नित करें।

वैध Retry-After हेडर मौजूद हो तो उसका पालन करें। हर त्रुटि में वह होगा, ऐसा न मानें। गैर-आइडेम्पोटेंट जनरेशन अनुरोध अपने-आप दोहराने से निष्पादन फिर हो सकता है और अतिरिक्त शुल्क लग सकता है। यह पृष्ठ सामान्य idempotency-key समर्थन का वादा नहीं करता; अपने-आप Idempotency-Key जोड़ना दोहराव हटाने की गारंटी नहीं।

पहले से jobId हो तो दूसरा जॉब बनाने से पहले वही क्वेरी करें। jobId न हो और परिणाम अनिश्चित हो तो जाँच के लिए अनुरोध पहचान और टाइमस्टैम्प रखें।

स्ट्रीम और असिंक्रोनस जॉब

SSE अनुरोध

SSE शुरू होने के बाद HTTP स्थिति 200 रह सकती है, जबकि बाद की विफलता स्ट्रीम में त्रुटि इवेंट या पेलोड से बताई जाती है। चुने प्रोटोकॉल के इवेंट और डेटा पार्स करें तथा सामान्य पूर्णता जाँचें। त्रुटि या अनपेक्षित डिस्कनेक्शन पर आंशिक पाठ या चित्र को पूरा सफल परिणाम न मानें। एंडपॉइंट के बीच इवेंट नाम और पेलोड अलग हैं। केवल एक निश्चित error फ़ील्ड न जाँचें और “कुछ भी पाठ मिला” को सफलता की शर्त न बनाएँ।

असिंक्रोनस जॉब

निर्माण उत्तर में data.jobId का अर्थ अनुरोध स्वीकार हुआ है, जनरेशन पूरा होना नहीं। जॉब क्वेरी में सफल HTTP उत्तर का अर्थ क्वेरी सफल है। जॉब का data.status फिर भी देखना होगा:

PENDING, CONNECT, PROCESSING: Jobs दस्तावेज़ के अनुसार पोलिंग जारी रखें।
COMPLETED: outputResult पढ़ें।
FAILED, CANCELLED: पोलिंग रोकें और जाँच के लिए जॉब ID तथा संवेदनशील जानकारी हटाया उत्तर रखें।

विफलता विवरण data.outputResult.error में आ सकता है। यह फ़ील्ड वैकल्पिक है और हर विफल जॉब में गारंटीकृत नहीं। Jobs तभी इस्तेमाल करें जब निर्माण उत्तर स्पष्ट रूप से jobId लौटाए। सीधे JSON या SSE परिणाम देने वाले एंडपॉइंट पर जॉब पोलिंग न लगाएँ।

उपयोगकर्ता और AI सहायक के लिए निदान

सहायता या AI सहायक को नीचे की संवेदनशील जानकारी हटाई सामग्री दें। अनुपस्थित फ़ील्ड के लिए unknown और HTTP उत्तर न मिलने पर HTTP स्थिति के लिए unknown दें। फ़ील्ड पथ और मूल मान प्रकार बनाए रखें, जैसे error.code: 10000 (number) या error.code: "invalid_api_key" (string)। स्ट्रिंग code को अपने-आप प्लेटफ़ॉर्म संख्यात्मक कोड में न बदलें और message, HTTP स्थिति या मॉडल नाम से अनुपलब्ध फ़ील्ड न गढ़ें।

text

time_with_timezone: unknown
method: unknown
path_without_query: unknown
model: unknown
stream: unknown
http_status: unknown
error_code_path_value_and_type: unknown
error_type_path_and_value: unknown
protocol_status_path_and_value: unknown
sanitized_message: unknown
request_id_from_body_or_X-Request-ID: unknown
job_id: unknown
job_status: unknown
retry_after: unknown
retry_count_and_delays: unknown
received_partial_output: unknown

उपलब्ध हो तो उत्तर बॉडी या X-Request-ID उत्तर हेडर से requestId पढ़ें। लंबी संख्याओं की सटीकता न खोने के लिए jobId स्ट्रिंग रखें। केवल न्यूनतम, संवेदनशील जानकारी हटाए अनुरोध पैरामीटर दें। API कुंजियाँ, टोकन, कुकी, पूरे प्रमाणीकरण हेडर, व्यक्तिगत जानकारी, निजी प्रॉम्प्ट और इनपुट फ़ाइल सामग्री हटाएँ। URL क्वेरी पैरामीटर और हस्ताक्षर या पहुँच क्रेडेंशियल वाले इनपुट/आउटपुट URL हटाएँ। समीक्षा बिना पूरे अनुरोध लॉग न पेस्ट करें।

AI सहायक देखे गए फ़ील्ड और संभावित कारण अलग रखें तथा अनुपलब्ध जानकारी पहचानें। अपर्याप्त प्रमाण को अनुरोध सफल होने, निष्पादित न होने या कोई शुल्क न लगने का प्रमाण न मानें।