त्रुटियाँ

हर विफल Bird API अनुरोध एक जैसी JSON त्रुटि प्रतिक्रिया लौटाता है, जो शीर्ष-स्तर की error कुंजी के अंदर होती है। खाली बॉडी वाले भेजने के अनुरोध की एक वास्तविक प्रतिक्रिया यह है:

कोड उदाहरण

{
  "error": {
    "type": "validation_error",
    "code": "E01001",
    "name": "ValidationError",
    "message": "Request has 1 validation error.",
    "doc_url": "https://bird.com/docs/api/errors/E01001",
    "request_id": "req_01ky7q3hckecgv6d7jpq865532",
    "details": [{ "param": "body", "message": "missing properties 'from', 'to'" }]
  }
}

HTTP स्टेटस type से तय होता है। क्लाइंट त्रुटियों में गलत बने अनुरोधों के लिए 400, एक्सेस विफलताओं के लिए 401 या 403, बिलिंग के लिए 402, और न मिलने वाले संसाधनों के लिए 404 का उपयोग होता है। टकराव के लिए 409, पूरी न हुई पूर्व-शर्तों के लिए 412, सत्यापन और व्यावसायिक नियमों की विफलताओं के लिए 422, और दर सीमाओं के लिए 429 का उपयोग होता है। Bird की ओर की विफलताओं के लिए 5xx का उपयोग होता है। स्टेटस श्रेणी बताता है; त्रुटि प्रतिक्रिया बताती है कि क्या हुआ।

त्रुटि प्रतिक्रिया के फ़ील्ड

फ़ील्ड	भूमिका
`type`	व्यापक स्तर पर शाखा बनाने के लिए मुख्य श्रेणी: `validation_error`, `auth_error`, `permission_error`, `not_found_error`, `conflict_error`, `rate_limit_error`, `billing_error`, `internal_error`, और कुछ अन्य। यह एक बंद एनम है, जिसमें कभी-कभार ही नए मान जुड़ते हैं।
`code`	अपारदर्शी, स्थिर पहचानकर्ता (`E01001`)। आधिकारिक संदर्भ: अद्वितीय, कभी नाम नहीं बदलता, कभी दोबारा उपयोग नहीं होता। जब कोई त्रुटि हटाई जाती है, तो उसका कोड स्थायी रूप से आरक्षित रहता है।
`name`	लॉग को पढ़ने में आसान बनाने के लिए मानव-पठनीय स्लग (`ValidationError`)। यह हमेशा `code` के साथ आता है, कभी उसकी जगह नहीं लेता।
`message`	मानव-पठनीय विवरण। स्थिर नहीं: इसके शब्द बिना सूचना के बदल सकते हैं। इसे दिखाएँ और लॉग करें, लेकिन कभी पार्स न करें।
`param`	इनपुट से जुड़ी त्रुटियों में वह फ़ील्ड जिसके कारण त्रुटि हुई। लागू न होने पर यह शामिल नहीं होता।
`doc_url`	इस कोड के दस्तावेज़ पेज का स्थिर लिंक।
`request_id`	हमेशा मौजूद रहता है और `X-Request-Id` प्रतिक्रिया हेडर के रूप में भी लौटाया जाता है। सहायता अनुरोधों में इसका उल्लेख करें, ताकि Bird ठीक उसी अनुरोध का पता लगा सके।
`details`	हर फ़ील्ड की सत्यापन समस्याएँ, प्रत्येक `{param, message}` के रूप में। यह केवल `validation_error` प्रतिक्रियाओं में मौजूद रहता है, और उनमें भी केवल उन्हीं में जो फ़ील्ड सूचीबद्ध करती हैं।
`remediation`	त्रुटि हल करने के लिए मनुष्य के पढ़ने योग्य अगला कदम। यह तब मौजूद होता है जब समाधान ज्ञात हो।
`next`	वे ऑपरेशन जो त्रुटि हल करते हैं, उसी क्रम में जिसमें उन्हें आज़माना है। यह उन त्रुटियों के लिए मौजूद होता है जिनका समाधान स्पष्ट रूप से तय है, जैसे पूरी न हुई पूर्व-शर्तें।
`vendor_code`	किसी डाउनस्ट्रीम सिस्टम से ज्यों-का-त्यों लिया गया कोड (जैसे SMTP प्रतिक्रिया कोड या भुगतान अस्वीकृति कोड)। यह केवल तब मौजूद होता है जब Bird किसी बाहरी सिस्टम का ऐसा कोड दिखा रहा हो जिस पर आप कार्रवाई करना चाहें।

सामान्य हैंडलिंग के लिए type पर और विशिष्ट हैंडलिंग के लिए code पर ब्रांच करें, message पर कभी नहीं। एक सामान्य क्लाइंट type के आधार पर निर्णय लेता है (rate_limit_error पर फिर से प्रयास करता है, validation_error उपयोगकर्ता को दिखाता है, internal_error पर किसी को अलर्ट भेजता है)। अलग-अलग code मानों का मिलान वह केवल उन कुछ त्रुटियों के लिए करता है जिन्हें वह विशेष रूप से संभालता है।

E04012 जैसे कोड जानबूझकर अपारदर्शी रखे गए हैं। किसी कोड का सरल अर्थ जानने के लिए त्रुटि का message पढ़ें, फिर उसका doc_url खोलें: हर कोड का एक पेज है जो बताता है कि क्या गलत हुआ और क्या करना है। पूरी सूची त्रुटि संदर्भ में है।

सत्यापन विफलताएँ: एक कोड, कई विवरण

फ़ील्ड-स्तर के सत्यापन में हर फ़ील्ड और विफलता के संयोजन के लिए अलग कोड नहीं होता। ज़्यादातर फ़ील्ड समस्याएँ E01001 ValidationError होती हैं। शीर्ष-स्तर का message बताता है कि क्या गलत है, और param फ़ील्ड का नाम बताता है। details ऐरे हर फ़ील्ड-स्तर की समस्या को {param, message} के रूप में सूचीबद्ध करता है, जैसे ऊपर दर्ज की गई भेजने की विफलता अपनी गायब प्रॉपर्टी सूचीबद्ध करती है। किसी संपर्क प्रॉपर्टी का नाम data के अंतर्गत उसकी कुंजी से दिया जाता है, जैसे data.plan। कुछ सत्यापन त्रुटियाँ param में एक ही फ़ील्ड का नाम देती हैं और उनमें details नहीं होता, इसलिए details मौजूद होने पर उसे पढ़ें। message स्ट्रिंग बदल सकती हैं, इसलिए उन्हें केवल दिखाएँ। समस्याओं को फ़ॉर्म फ़ील्ड से जोड़ने के लिए param का उपयोग करें।

समाधान मार्गदर्शन: remediation और next

जिन त्रुटियों का समाधान ज्ञात है, उनकी प्रतिक्रिया में वह समाधान शामिल होता है। यह एक वेबहुक कॉल की वास्तविक प्रतिक्रिया है, जो ऐसी API कुंजी से की गई थी जिसमें ज़रूरी स्कोप नहीं है:

कोड उदाहरण

{
  "error": {
    "type": "permission_error",
    "code": "E02035",
    "name": "InsufficientScope",
    "message": "This request requires the \"webhooks:read\" scope, which your credential has not been granted.",
    "param": "webhooks:read",
    "doc_url": "https://bird.com/docs/api/errors/E02035",
    "request_id": "req_01ky7q4665emc9tw1pxkptaqwq",
    "remediation": "Re-authenticate with a credential that has been granted the required scope, then retry."
  }
}

remediation किसी व्यक्ति या एजेंट लॉग के लिए एक वाक्य है। next, जब मौजूद हो, उन API ऑपरेशनों की सूची देता है जो त्रुटि को हल करते हैं, उसी क्रम में जिसमें उन्हें आज़माना है (पहले डोमेन सत्यापित करें, फिर भेजने का फिर से प्रयास करें)। एजेंट और CLI next को सीधे चला सकते हैं, और इंटरैक्टिव क्लाइंट remediation को जैसा है वैसा दिखा सकते हैं।

त्रुटियों को सही तरीके से संभालना

फिर से प्रयासों की सीमा तय करें और ऑपरेशन की पहचान बनाए रखें। अनुरोध दर सीमाओं पर Retry-After का पालन करें (अनुरोध दर सीमाएँ देखें)। पढ़ने वाले अनुरोधों को सीमित बैकऑफ़ के साथ फिर से प्रयास करें। लिखने वाले अनुरोधों के लिए Idempotency-Key का उपयोग करें, ताकि तीन घंटे के भीतर मेल खाने वाले फिर से प्रयास ठीक एक बार स्वीकार हों। वही कुंजी और बिल्कुल वही अनुरोध दोबारा भेजें। फिर से प्रयास खत्म होने या समय-सीमा बीतने के बाद भी जिन ऑपरेशनों का परिणाम अज्ञात है, उन्हें मिलान होने तक अनसुलझा मानें।
code, name और request_id को एक साथ लॉग करें। कोड वह है जिसे आप दस्तावेज़ों और अपने लॉग में खोजेंगे। अनुरोध ID वह है जिसकी सपोर्ट को ज़रूरत होती है।
नए कोड और प्रकारों को स्वीकार करने लायक कोड लिखें। प्रोडक्ट बढ़ने के साथ नए त्रुटि कोड नियमित रूप से जुड़ते हैं, और type एनम में कभी-कभी नया मान जुड़ता है। अपने हैंडलर में हर मान का अलग मिलान करने के बजाय एक समझदार डिफ़ॉल्ट ब्रांच रखें।

अगले कदम

त्रुटि संदर्भ: पूरी त्रुटि सूची, हर कोड के लिए एक पेज
आइडेम्पोटेंसी: डेटा बदलने वाले अनुरोधों के लिए फिर से प्रयास का अनुबंध और डेटा रखे जाने की अवधि
अनुरोध दर सीमाएँ: सीमा हेडर और बैकऑफ़ से जुड़े निर्देश

इस विषय के लिए दस्तावेज़, गाइड और उदाहरणों के साथ आगे बढ़ें।

इम्प्लीमेंटेशन ब्रीफ़ पाएँ