त्रुटियाँ

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

कोड उदाहरण

{
  "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, और कुछ अन्य। एक closed enum जो शायद ही कभी बढ़ता है।
code	अपारदर्शी, स्थिर पहचानकर्ता (E01001)। मानक संदर्भ: अद्वितीय, कभी नाम नहीं बदलता, कभी पुन: उपयोग नहीं होता। जब कोई त्रुटि हटाई जाती है, तो उसका कोड स्थायी रूप से आरक्षित हो जाता है।
name	लॉग पठनीयता के लिए मानव-पठनीय slug (ValidationError)। हमेशा code के साथ जोड़ा जाता है, कभी इसका विकल्प नहीं।
message	मानव-पठनीय विवरण। स्थिर नहीं: शब्द बिना सूचना बदल सकते हैं। इसे दिखाएँ, लॉग करें, कभी पार्स न करें।
param	इनपुट-संबंधित त्रुटियों के लिए, समस्याग्रस्त फ़ील्ड। लागू न होने पर छोड़ दिया जाता है।
doc_url	इस कोड के डॉक्स पेज का स्थिर लिंक।
request_id	हमेशा मौजूद, और X-Request-Id रिस्पॉन्स हेडर के रूप में भी लौटाया जाता है। सपोर्ट अनुरोधों में इसे उद्धृत करें; यह Bird को सटीक अनुरोध ट्रेस करने देता है।
details	प्रति-फ़ील्ड सत्यापन समस्याएँ। केवल validation_error रिस्पॉन्स में मौजूद।
remediation	त्रुटि हल करने के लिए मानव-पठनीय अगला कदम। रिकवरी ज्ञात होने पर मौजूद।
next	त्रुटि हल करने वाले ऑपरेशन, आज़माने के क्रम में। स्पष्ट रिकवरी वाली त्रुटियों के लिए मौजूद, जैसे अपूर्ण पूर्वशर्तें।
vendor_code	डाउनस्ट्रीम सिस्टम से हूबहू कोड (एक SMTP रिस्पॉन्स कोड, एक पेमेंट डिक्लाइन कोड)। केवल तब मौजूद जब Bird किसी बाहरी सिस्टम का कोड सामने ला रहा हो जिस पर आप कार्रवाई करना चाहें।

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

E04012 जैसे कोड जानबूझकर अपारदर्शी हैं। हर कोड doc_url के ज़रिए एक डॉक्यूमेंटेशन पेज से जुड़ा है, जो कारण और समाधान बताता है। पूरा कैटलॉग त्रुटि संदर्भ में है।

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

फ़ील्ड-स्तरीय सत्यापन में प्रत्येक फ़ील्ड-और-विफलता संयोजन के लिए अलग कोड नहीं मिलता। हर सत्यापन विफलता E01001 ValidationError होती है, जिसमें एक details array प्रत्येक फ़ील्ड-स्तरीय समस्या को {param, message} के रूप में सूचीबद्ध करता है, ठीक उसी तरह जैसे कैप्चर किए गए send विफलता में उसकी अनुपलब्ध प्रॉपर्टीज़ सूचीबद्ध होती हैं। details के अंदर message स्ट्रिंग बदल सकती हैं और केवल प्रदर्शित की जानी चाहिए। समस्याओं को फ़ॉर्म फ़ील्ड से मैप करने के लिए param का उपयोग करें।

रिकवरी मार्गदर्शन: उपचार और अगला कदम

ज्ञात समाधान वाली त्रुटियाँ इसे त्रुटि प्रतिक्रिया में रखती हैं। यह एक webhooks कॉल का वास्तविक रिस्पॉन्स है जो एक ऐसी API key से किया गया जिसमें आवश्यक scope नहीं है:

कोड उदाहरण

{
  "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 ऑपरेशनों को आज़माने के क्रम में सूचीबद्ध करता है (डोमेन सत्यापित करें, फिर send फिर से प्रयास करें)। एजेंट और CLI next को सीधे निष्पादित कर सकते हैं; इंटरैक्टिव क्लाइंट remediation को जैसा है वैसा दिखा सकते हैं।

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

डिफ़ॉल्ट रूप से केवल 429 और 5xx पर फिर से प्रयास करें, बाकी पर नहीं। अनुरोध दर सीमाओं पर Retry-After का पालन करें (देखें अनुरोध दर सीमाएँ), 5xx पर exponential backoff का उपयोग करें, और एक Idempotency-Key भेजें ताकि म्यूटेटिंग अनुरोधों के फिर से प्रयास सुरक्षित रहें।
code, name, और request_id को एक साथ लॉग करें। कोड वह है जिसे आप डॉक्स और अपने लॉग में खोजेंगे; request ID वह है जो सपोर्ट को चाहिए।
नए कोड और प्रकार सहन करें। नए त्रुटि कोड नियमित रूप से आते हैं जैसे-जैसे प्रोडक्ट बढ़ते हैं, और type enum में कभी-कभी नई वैल्यू जुड़ती है। अपने हैंडलर को exhaustive match की बजाय एक समझदार default ब्रांच के साथ लिखें।

अगले कदम

त्रुटि संदर्भ: पूरा त्रुटि कैटलॉग, प्रति कोड एक पेज
Idempotency: म्यूटेटिंग अनुरोधों के लिए सुरक्षित फिर से प्रयास
अनुरोध दर सीमाएँ: limit हेडर और backoff मार्गदर्शन