Errors और Status codes

CLI exit codes, SDK exceptions, और REST API error responses के लिए reference।

Roboflow के डेवलपर टूल्स त्रुटि श्रेणियों का एक छोटा सेट साझा करते हैं, जिसे हर टूल में अलग तरह से दिखाया जाता है। यह पेज एक समग्र संदर्भ है।

CLI एग्ज़िट कोड

CLI चार सुव्यवस्थित एग्ज़िट कोड का उपयोग करता है, ताकि स्क्रिप्ट और AI एजेंट आउटपुट को पार्स किए बिना परिणाम के आधार पर शाखा बना सकें:

एग्ज़िट कोड	अर्थ
0	सफलता
1	सामान्य त्रुटि (गलत इनपुट, नेटवर्क विफलता, अप्रत्याशित सर्वर प्रतिक्रिया)
2	प्रमाणीकरण विफलता (API key अनुपस्थित या अमान्य, कोई वर्कस्पेस चयनित नहीं)
3	संसाधन नहीं मिला (प्रोजेक्ट, वर्ज़न, वर्कफ़्लो, डिप्लॉयमेंट आदि मौजूद नहीं है या आपकी key को दिखाई नहीं देता)

में --json इस मोड में CLI सफलता पर structured output stdout पर लिखता है और विफलता पर stderr पर JSON error object लिखता है, stdout को खाली छोड़ता है ताकि pipelines को सुरक्षित रूप से पार्स किया जा सके:

roboflow --json project get nonexistent 2>error.json
echo $?       # 3
cat error.json
# {"error": {"message": "प्रोजेक्ट 'nonexistent' नहीं मिला", "hint": "अपने प्रोजेक्ट देखने के लिए 'roboflow project list' चलाएँ."}}

SDK अपवाद

Python SDK विफलता पर Python exceptions उठाता है। जिन सबसे सामान्य प्रकारों का आप सामना करेंगे:

अपवाद	कब
RuntimeError	ऑपरेशन तार्किक रूप से अमान्य है - उदाहरण के लिए, कॉल करना restore() ऐसे प्रोजेक्ट पर जो Trash में नहीं है, या ऐसे वर्ज़न पर ट्रेनिंग करना जो अभी जनरेट नहीं हुआ है।
ValueError	कोई पास किया गया आर्ग्यूमेंट गलत-आकार का है - उदाहरण के लिए, एक अपरिचित model_format के लिए Version.download().
roboflow.adapters.rfapi.RoboflowError	REST API ने non-2xx प्रतिक्रिया लौटाई। अपवाद के string में सर्वर का error body शामिल होता है।
roboflow.adapters.deploymentapi.DeploymentApiError	के समकक्ष RoboflowError समर्पित-deployments सेवा के लिए।
requests.exceptions.HTTPError / ConnectionError	नेटवर्क-स्तरीय विफलताएँ (DNS, TLS, टाइमआउट)।

सामान्य नियम: पकड़ें RuntimeError तार्किक समस्याओं के लिए, RoboflowError सर्वर-पक्ष अस्वीकृतियों के लिए, और बाकी सबको ऊपर जाने दें।

from roboflow.adapters import rfapi

try:
    project.restore()
except RuntimeError as e:
    print(f"Can't restore: {e}")
except rfapi.RoboflowError as e:
    print(f"Server rejected the request: {e}")

देखें लॉगिंग और डीबगिंग यह जानने के लिए कि जब कोई अपवाद पर्याप्त न हो, तब अंतर्निहित HTTP अनुरोध की जाँच कैसे करें।

REST API स्थिति कोड

REST API मानक HTTP स्थिति कोड का उपयोग करती है। Roboflow-विशिष्ट व्यवहार:

स्थिति	अर्थ
200	सफलता। प्रतिक्रिया बॉडी JSON है।
204	सफलता, कोई बॉडी नहीं (कुछ के लिए उपयोग किया जाता है PATCH / DELETE endpoints)।
400	गलत संरचित अनुरोध - आवश्यक फ़ील्ड अनुपस्थित, खराब संरचना, अमान्य मान।
401	प्रमाणीकरण विफलता। या तो कोई api_key , एक अमान्य, या ऐसा key जिसमें ऑपरेशन के लिए आवश्यक scope नहीं है।
402	भुगतान आवश्यक है। वर्कस्पेस की योजना अनुरोधित ऑपरेशन का समर्थन नहीं करती। inference के लिए, इसका अर्थ है कि model या architecture केवल credit-based plan पर उपलब्ध है, या वर्कस्पेस की मासिक Hosted API inference quota पूरी हो चुकी है। प्रतिक्रिया बॉडी में एक AccessException त्रुटि प्रकार।
403	निषिद्ध। key प्रमाणित तो हुआ, लेकिन लक्ष्य वर्कस्पेस या संसाधन तक पहुँच नहीं है।
404	नहीं मिला। वर्कस्पेस, प्रोजेक्ट, वर्ज़न, वर्कफ़्लो, या अन्य संसाधन मौजूद नहीं है (या आपकी key को दिखाई नहीं देता)।
409	टकराव। संसाधन ऐसी स्थिति में मौजूद है जो अनुरोधित ऑपरेशन को रोकती है (उदाहरण के लिए, ऐसे वर्ज़न को पुनर्स्थापित करना जिसका parent project भी Trash में है)।
423	लॉक्ड। वर्कस्पेस बिलिंग रोकी गई है - कारण के लिए प्रतिक्रिया बॉडी देखें।
429	दर सीमित। गति कम करें और exponential backoff के साथ पुनः प्रयास करें।
5xx	सर्वर त्रुटि। backoff के साथ पुनः प्रयास करना सुरक्षित है।

मानक त्रुटि बॉडी

त्रुटियाँ JSON लौटाती हैं जिसमें कम-से-कम एक शीर्ष-स्तरीय त्रुटि फ़ील्ड:

{
  "error": "प्रोजेक्ट 'nonexistent' नहीं मिला"
}

कुछ endpoints में एक संकेत या एक संरचित त्रुटि ऑब्जेक्ट - विशिष्ट जानकारी के लिए प्रति-endpoint दस्तावेज़ के तहत देखें REST API ।

आवश्यक scope

API keys में प्रति-संसाधन scopes होते हैं। किसी write ऑपरेशन से मिला 401 अक्सर इसका मतलब है कि key के पास संबंधित *:update या *:write scope नहीं है, भले ही वह संसाधन को पढ़ सकता हो। देखें स्कोप्ड API कुंजियाँ scope संदर्भ के लिए।

टूल्स के बीच त्रुटि मैपिंग

स्थिति	CLI एग्ज़िट	एसडीके	REST
अनुपस्थित / अमान्य API key	2	RoboflowError ("401")	401
संसाधन नहीं मिला	3	RoboflowError ("404") / RuntimeError	404
योजना की सीमा / कोटा पार	1	RoboflowError ("402")	402
गलत इनपुट / गलत संरचित अनुरोध	1	ValueError / RoboflowError ("400")	400
सर्वर त्रुटि / अस्थायी	1	RoboflowError ("5xx")	5xx

पुनः प्रयास सेट करते समय इस तालिका का उपयोग करें: एक 2 / 401 को कभी भी स्वचालित रूप से पुनः प्रयास नहीं किया जाना चाहिए (key अधिक वैध नहीं होगी), एक 3 / 404 को कभी भी पुनः प्रयास नहीं किया जाना चाहिए, लेकिन एक 1 5xx प्रतिक्रिया से आने वाला प्रत्युत्तर backoff के साथ पुनः प्रयास के लिए उपयुक्त उम्मीदवार है।