- API अनुरोध त्रुटियाँ — किसी सिंक्रोनस API कॉल की HTTP प्रतिक्रिया (प्रमाणीकरण, बिलिंग, गलत ढंग से बने अनुरोध, अनुपलब्ध संसाधन)। देखें API अनुरोध त्रुटियाँ।
- Prediction विफलता कोड — अनुरोध स्वीकार होकर कतार में चला गया, लेकिन prediction स्वयं
status: "failed"के साथ समाप्त हुई। विफलता का वर्णन prediction पर मौजूदerrorऑब्जेक्ट करता है, जो आपको prediction status एंडपॉइंट से, webhook डिलीवरी से और result एंडपॉइंट से मिलता है। देखें Prediction विफलता कोड।
Prediction विफलता कोड
विफल prediction अपने साथ एकerror ऑब्जेक्ट लेकर आती है:
विफल predictions के लिए शुल्क नहीं लिया जाता; अनुरोध के लिए आरक्षित क्रेडिट वापस जारी कर दिए जाते हैं।
जो prediction विफल नहीं हुई, वह
error: null लेकर आती है। यदि आपका इंटीग्रेशन 17 अगस्त 2026 से पहले का है, तो देखें माइग्रेशन नोट।
त्रुटि आपको कहाँ मिलती है
वहीerror ऑब्जेक्ट हर चैनल पर प्रकाशित होता है, इसलिए आप जहाँ पहले से देखते हैं वहीं उसे पढ़ सकते हैं:
result एंडपॉइंट से विफलता पढ़ना
जो prediction विफल हो चुकी है उसका आउटपुट माँगने पर400 मिलता है, जिसमें वही विफलता होती है जो इसका कारण बनी — अनुरोध-स्तरीय कोड PREDICTION_FAILED के अंतर्गत:
error.codeका मानPREDICTION_FAILEDहै, जो एक API अनुरोध त्रुटि है और जिसका अर्थ है “जिस prediction का आउटपुट आपने माँगा, उसने कोई आउटपुट नहीं दिया”;error.detailsprediction का अपनाerrorऑब्जेक्ट है — उसी अनुरोध के लिए/statusजो बताता है, ठीक वही, इसलिए दोनों एंडपॉइंट विफलता के कारण पर कभी अलग बात नहीं कह सकते। शाखाकरणerror.details.reasonऔरerror.details.retryableपर करें।
error.message prediction के message को ही दोहराता है, इसलिए जो क्लाइंट केवल शीर्ष-स्तरीय message पढ़ता है उसे भी काम की जानकारी मिल जाती है।
दो timestamp, दो अर्थ। शीर्ष-स्तरीय timestamp बताता है कि यह HTTP प्रतिक्रिया कब बनी; error.details.timestamp बताता है कि prediction कब विफल हुई। जिस prediction को आप कई दिन बाद लाते हैं, उसमें दोनों के बीच कई दिनों का अंतर होगा। विफलता की बात करते समय हमेशा भीतर वाला पढ़ें।
आधिकारिक क्लाइंट लाइब्रेरियाँ यह काम आपके लिए कर देती हैं: result() जो त्रुटि फेंकता है उसके code, reason और retryable prediction के अपने मान होते हैं, ठीक वही जो उसी विफलता के लिए subscribe() फेंकता है।
जो prediction अब भी कतार में है या चल रही है, या जिसे रद्द कर दिया गया है, वह पहले की तरह वही सामान्य 400 लौटाती रहती है।
दोबारा प्रयास करें या नहीं, यह कैसे तय करें
retryable देखें। यह ठीक एक ही प्रश्न का उत्तर देता है — यही अनुरोध हूबहू दोबारा भेजने पर क्या परिणाम अलग होगा? — और यह code से स्वतंत्र है: एक ही code एक विफलता में दोबारा प्रयास योग्य हो सकता है और दूसरी में नहीं।
retryable वैकल्पिक है। जब यह अनुपस्थित हो, तो नीचे दी गई तालिका में code के अनुसार डिफ़ॉल्ट पर लौट जाएँ। यह फ़ील्ड आने से पहले Sunra का यही व्यवहार था, इसलिए इस पर लौटना हमेशा सुरक्षित है; बस कम सटीक है।
code
reason
reason, code के पीछे के विशिष्ट कारण का नाम बताता है। इसका उपयोग मेट्रिक्स, रूटिंग और सहायता-निदान के लिए करें; दोबारा प्रयास के निर्णय के लिए retryable का उपयोग करें।
आज प्रकाशित हर reason का नीचे अपना अलग खंड है, और उसका ऐंकर स्वयं reason ही है — #input_fetch_failed, #moderation_blocked इत्यादि — ताकि कोई त्रुटि रिपोर्ट सीधे उसके अर्थ तक जोड़ सके।
input_validation_failed
code: invalid_input · retryable: false
अनुरोध Sunra के अपने schema या पैरामीटर सत्यापन में विफल रहा। message समस्याग्रस्त फ़ील्ड का नाम बताता है।
क्या करें: बताए गए फ़ील्ड को ठीक करें। वही अनुरोध बार-बार विफल होता रहेगा।
provider_rejected_input
code: invalid_input · retryable: false
मॉडल provider ने एक या अधिक इनपुट पैरामीटर अस्वीकार कर दिए। जहाँ provider हमें बताता है कि कौन-सा, वहाँ message उसे आगे बताता है; कुछ providers केवल इतना बताते हैं कि इनपुट स्वीकार्य नहीं था, और ऐसे में हम अनुमान लगाने के बजाय ठीक यही कहते हैं।
क्या करें: अपने पैरामीटरों को मॉडल के schema के सामने रखकर जाँचें — सीमा से बाहर कोई मान, असमर्थित संयोजन, या ऐसा आस्पेक्ट रेशियो या अवधि जिसे मॉडल स्वीकार नहीं करता।
input_fetch_failed
code: invalid_input · retryable: false या true
URL से संदर्भित कोई इनपुट फ़ाइल लाई नहीं जा सकी। यही एकमात्र reason है जिसमें retryable वास्तव में बदलता है, इसलिए अनुमान लगाने के बजाय फ़ील्ड पढ़ें:
false— होस्ट ने हमें अस्वीकार किया:4xx, ऐसा पता जहाँ से लाने की अनुमति हमें नहीं है, रीडायरेक्ट, या आकार सीमा से बड़ी फ़ाइल;true— होस्ट क्षण भर के लिए अनुपलब्ध था:5xx, टाइमआउट, या DNS विफलता।
message आपके भेजे गए URL को दोहराता है ताकि आप पहचान सकें कि कौन-सा इनपुट विफल हुआ — उसकी query string हटाकर, ताकि presigned URL में मौजूद क्रेडेंशियल कभी आपको वापस न लौटाए जाएँ:
retryable false हो, तो जाँचें कि URL सार्वजनिक रूप से पहुँच योग्य है और presigned लिंक समाप्त तो नहीं हो गया। जब वह true हो, तो दोबारा प्रयास करें।
moderation_blocked
code: unsafe_content · retryable: false
मॉडल provider की सामग्री सुरक्षा प्रणाली द्वारा अवरुद्ध — चाहे भीतर जाने वाला prompt और इनपुट मीडिया हो, या वापस आने वाला उत्पन्न आउटपुट।
क्या करें: prompt या मीडिया बदलें। वही सामग्री दोबारा भेजने पर फिर रोकी जाएगी।
provider_rate_limited
code: service_provider_error · retryable: true
मॉडल provider अनुरोधों पर दर सीमा लगा रहा है।
क्या करें: बैकऑफ़ के साथ दोबारा प्रयास करें, या किसी दूसरे मॉडल पर रूट करें।
provider_unavailable
code: service_provider_error · retryable: true
मॉडल provider अनुरोध पूरा नहीं कर सका।
क्या करें: बाद में दोबारा प्रयास करें, या किसी दूसरे मॉडल पर रूट करें।
provider_timeout
code: task_timeout · retryable: true
prediction निर्धारित समय में पूरी नहीं हुई।
क्या करें: दोबारा प्रयास करें — कम भार का समय, या छोटा अनुरोध (कम अवधि, कम रिज़ॉल्यूशन) सफलता की संभावना बढ़ाता है।
provider_account_error
code: internal_server_error · retryable: false
मॉडल provider के पास हमारे अपने खाते में कोई समस्या है — बिलिंग, क्रेडेंशियल, या स्थायी कोटा। यह गड़बड़ी हमारी ओर की है, आपके इनपुट की नहीं।
क्या करें: आपकी ओर से कुछ नहीं; दोबारा प्रयास से कुछ नहीं होगा और हमें स्वतः अलर्ट मिल जाता है। यदि आपको यह क्षमता अभी चाहिए तो किसी दूसरे मॉडल पर रूट करें।
endpoint_misconfigured
code: internal_server_error · retryable: false
यह मॉडल एंडपॉइंट हमारी ओर से गलत कॉन्फ़िगर है।
क्या करें: आपकी ओर से कुछ नहीं; दोबारा प्रयास से कुछ नहीं होगा और हमें स्वतः अलर्ट मिल जाता है। अत्यावश्यक हो तो request_id के साथ सहायता टीम से संपर्क करें।
queue_enqueue_failed
code: internal_server_error · retryable: true
prediction को कतार में नहीं डाला जा सका।
क्या करें: अनुरोध दोबारा सबमिट करें।
reaped_stalled
code: internal_server_error · retryable: true
prediction अटक गई और उसे समाप्त कर दिया गया।
क्या करें: अनुरोध दोबारा सबमिट करें।
अज्ञात मान
code और reason दोनों खुले समुच्चय हैं। जैसे-जैसे हम और अधिक विफलताओं को वर्गीकृत करते हैं, नए मान जुड़ते जाते हैं — बिना किसी breaking change घोषणा के। कोई अपरिचित मान मिलने पर आपके इंटीग्रेशन को क्रैश नहीं होना चाहिए, त्रुटि को गिराना नहीं चाहिए, और न ही पूरे payload को अस्वीकार करना चाहिए।
- अज्ञात
reason— इसे ऐसे मानें जैसेreasonअनुपस्थित हो, औरretryable(याcodeके अनुसार डिफ़ॉल्ट) से निर्णय लें। कच्चा मान अपने लॉग में रखें; सहायता टीम के लिए विफलता पहचानने का यही सबसे तेज़ रास्ता है। - अज्ञात
code— इसेinternal_server_errorमानें। एक प्रहरी मान नाम से जानने लायक है:unknown_error_code, जिसे Sunra तब भेजता है जब prediction विफल तो हुई हो, पर उसके लिए कोई वर्गीकरण प्राप्त न किया जा सका हो।
माइग्रेशन नोट: कोई त्रुटि न होने पर error का मान null होता है
17 अगस्त 2026 से प्रभावी। error ऑब्जेक्ट का हर चैनल पर एक ही रूप है। इनके बीच के तीन अंतर अब समाप्त हो गए हैं:
- prediction विफल न हुई हो, तो
errorका मानnullहोता है।GET /v1/predictions/{prediction_id}पहले हर सफल, कतारबद्ध और रद्द की गई prediction पर एक खाली ऑब्जेक्ट —"error": {}— लौटाता था। अब वह"error": nullलौटाता है, जो queue status एंडपॉइंट पहले से ही करता आ रहा था। यदि आप खालीपन की जाँच करते हैं (Object.keys(response.error).length === 0), तो उसकी जगह null जाँच (response.error === null) रखें। - विफलता हमेशा अपने साथ गैर-रिक्त
codeऔरmessageलेकर आती है। जिस विफलता में ऐसा कुछ दर्ज हुआ जिसे हम वर्गीकृत नहीं कर सकते, वहाँ अब आपकोunknown_error_codeप्रहरी मान और एक सामान्य message मिलता है — न कि ऐसा फ़ील्ड जो अनुपस्थित हो, खाली हो, या स्ट्रिंग न हो। - सादे टेक्स्ट के रूप में दर्ज विफलताएँ आप तक टेक्स्ट के रूप में ही पहुँचती हैं। अप्रैल 2026 की गिनी-चुनी predictions ने अपनी त्रुटि केवल एक स्ट्रिंग के रूप में संग्रहित की थी।
GET /v1/predictions/{prediction_id}उसे पहले गिरा देता था, और queue status एंडपॉइंट उसकी जगह प्रहरी message रख देता था; अब दोनों उसेcode: "unknown_error_code"के अंतर्गतmessageके रूप में प्रकाशित करते हैं।
error इनमें से हर प्रतिक्रिया में पहले से मौजूद था, बदला केवल उसका मान है। Webhook डिलीवरी अछूती हैं — बाकी चैनल जिस रूप पर आकर मिले, वह यही था — और succeeded डिलीवरी में error पहले की तरह अनुपस्थित ही रहता है, उसे null के रूप में नहीं भेजा जाता।
संगतता अवधि। दोहरे उत्सर्जन की कोई अवधि नहीं है; उस तारीख से API ने "error": {} बनाना बंद कर दिया। यदि आप उससे पहले पकड़े गए payloads दोबारा चलाते या दोबारा संसाधित करते हैं, तो जब तक वह संग्रहित डेटा पुराना होकर निकल न जाए, तब तक null और {} को एक ही चीज़ मानें।
आगामी बदलाव: कुछ विफलताओं को अधिक विशिष्ट code मिलेगा
आज विफलताओं का एक बड़ा हिस्सा service_provider_error के रूप में रिपोर्ट होता है, जिनमें कई ऐसी हैं जो न क्षणिक हैं और न ही provider की गलती। जैसे-जैसे हम एक-एक करके providers को वर्गीकृत करते हैं, वे विफलताएँ उस code पर चली जाती हैं जो वास्तव में उनका वर्णन करता है:
- provider द्वारा आपके इनपुट को निश्चित रूप से अस्वीकार किया जाना अब
invalid_inputहोगा (पहलेservice_provider_error); - Sunra की ओर की समस्या, जैसे गलत कॉन्फ़िगर एंडपॉइंट या provider के पास हमारा अपना खाता, अब
internal_server_errorहोगी (पहलेservice_provider_error); - ऐसी इनपुट फ़ाइल जिसे हम ला नहीं सके, अब
invalid_inputहोगी (पहलेinternal_server_error)।
code मान भी नहीं जोड़ा जा रहा — ऊपर दिए गए पाँच मान ही वर्गीकृत codes का पूरा समुच्चय बने रहते हैं। जो बदलता है वह यह है कि किसी विफलता को इनमें से कौन-सा मिलेगा, और यह क्रमिक रूप से, एक-एक provider करके बदलता है। यदि आपका कोड code के आधार पर शाखाएँ बनाता है, तो उस तर्क को retryable और reason पर ले जाने का यह अच्छा अवसर है: ये दोनों विफलता का सीधा वर्णन करते हैं और इस पुनर्वर्गीकरण से प्रभावित नहीं होते।