त्रुटि प्रतिक्रियाएँ
हर विफल अनुरोध एक ही JSON एनवेलप लौटाता है, जो एक शीर्ष-स्तरीय error कुंजी के अंतर्गत होता है और जिसमें एक HTTP स्टेटस मोटी श्रेणी बताता है। यह पेज वायर कॉन्ट्रैक्ट है; ब्रांचिंग, फिर से प्रयास, और कोड कैटलॉग दर्शन के मार्गदर्शन के लिए त्रुटियाँ देखें।
{
"error": {
"type": "validation_error",
"code": "E01001",
"name": "ValidationError",
"message": "Request validation failed.",
"doc_url": "https://bird.com/docs/api/errors/E01001",
"request_id": "req_01krdgeqcxet5s7t44vh8rt9mg",
"details": [
{ "param": "contact_id", "message": "this field is reserved and not yet supported" },
{ "param": "topic_id", "message": "this field is reserved and not yet supported" }
]
}
}एनवेलप फ़ील्ड
| फ़ील्ड | हमेशा मौजूद | विवरण |
|---|---|---|
type | हाँ | मोटी ब्रांचिंग के लिए व्यापक श्रेणी: एक बंद एनम (auth_error, validation_error, rate_limit_error, ...)। |
code | हाँ | E\d{5} से मेल खाने वाला अपारदर्शी, स्थिर पहचानकर्ता। अद्वितीय, कभी नाम नहीं बदला जाता, कभी पुन: उपयोग नहीं होता; मिलान के लिए यही मानक है। |
name | हाँ | लॉग पठनीयता के लिए मानव-पठनीय स्लग (ValidationError)। हमेशा code के साथ जोड़ा जाता है, कभी इसका विकल्प नहीं। |
message | हाँ | मानव-पठनीय विवरण। स्थिर नहीं; इसे प्रदर्शित या लॉग करें, कभी पार्स न करें। |
doc_url | हाँ | इस code के दस्तावेज़ पेज का स्थिर लिंक। |
request_id | हाँ | सहसंबंध ID, जो X-Request-Id रिस्पॉन्स हेडर के रूप में भी लौटाया जाता है। सपोर्ट अनुरोधों में इसे उद्धृत करें। |
param | नहीं | दोषी फ़ील्ड, जब कोई एक फ़ील्ड गलत हो। |
details | नहीं | {param, message} ऑब्जेक्ट के रूप में प्रति-फ़ील्ड वैलिडेशन विफलताएँ, जहाँ param एक डॉटेड पथ है जैसे to[0].email। केवल validation_error प्रतिक्रियाओं पर मौजूद। |
vendor_code | नहीं | डाउनस्ट्रीम सिस्टम से मिला यथावत कोड (जैसे SMTP रिप्लाई कोड या भुगतान अस्वीकृति कोड), जब वह सिस्टम ऐसा कोड लौटाता है। |
HTTP स्टेटस मैपिंग
प्रत्येक type ठीक एक HTTP स्टेटस से मैप होता है, इसलिए स्टेटस और एनवेलप कभी असहमत नहीं होते।
| स्टेटस | type | अर्थ |
|---|---|---|
400 | bad_request_error | अनुरोध विकृत था: एक अपार्स करने योग्य बॉडी या एक अमान्य हेडर (उदाहरण के लिए, एक खराब Idempotency-Key)। |
401 | auth_error | अनुरोध में अनुपस्थित, अमान्य, या निरस्त क्रेडेंशियल थे। प्रमाणीकरण देखें। |
402 | billing_error | अनुरोध के लिए एक भुगतान विधि, शेष, या योजना आवश्यक है जो संगठन के पास नहीं है। बिलिंग और उपयोग देखें। |
403 | permission_error | क्रेडेंशियल मान्य हैं, लेकिन इस अनुरोध को करने की अनुमति नहीं है। प्रमाणीकरण देखें। |
404 | not_found_error | इस पथ से कोई रूट मेल नहीं खाता, या संसाधन इस वर्कस्पेस में मौजूद नहीं है। क्षेत्र देखें। |
409 | conflict_error | अनुरोध संसाधन की वर्तमान स्थिति से विरोध करता है, जिसमें आइडेम्पोटेंसी विरोध (E01004, E01005) शामिल हैं। आइडेम्पोटेंसी देखें। |
410 | gone_error | संसाधन मौजूद था लेकिन स्थायी रूप से हटा दिया गया है। |
412 | precondition_error | इस अनुरोध की कोई पूर्व शर्त पूरी नहीं हुई। |
413 | payload_too_large_error | अनुरोध बॉडी अधिकतम अनुमत आकार से अधिक है। |
421 | misdirected_error | अनुरोध ऐसे क्षेत्र तक पहुँचा जो इसे सर्व नहीं कर सकता। क्षेत्र देखें। |
422 | delivery_error | संदेश अनुरोध के रूप में स्वीकार किया गया लेकिन दिए गए पते पर डिलीवर नहीं किया जा सकता। |
422 | validation_error | अनुरोध बॉडी पार्स हो गई, लेकिन एक या अधिक मान अमान्य हैं। |
425 | too_early_error | अनुरोध उस समय से पहले पहुँच गया जब उसे प्रोसेस किया जा सकता है। |
429 | rate_limit_error | इस वर्कस्पेस के लिए एक अनुरोध दर-सीमा समूह समाप्त हो गया है। अनुरोध दर सीमाएँ देखें। |
499 | client_closed_request_error | प्रतिक्रिया तैयार होने से पहले कनेक्शन बंद हो गया, आमतौर पर इसलिए कि कॉलर ने प्रतीक्षा करना बंद कर दिया। |
500 | internal_error | अनुरोध को प्रोसेस करते समय हमारी तरफ़ कुछ विफल हो गया। आइडेम्पोटेंसी देखें। |
501 | not_implemented_error | यह एंडपॉइंट API में घोषित है लेकिन अभी तक लागू नहीं किया गया है। |
503 | service_unavailable_error | इस अनुरोध की कोई निर्भरता अस्थायी रूप से अनुपलब्ध है। |
SDK में त्रुटियों को हैंडल करना
प्रत्येक SDK एनवेलप को अपनी भाषा के नेटिव त्रुटि मॉडल पर मैप करता है और हर एनवेलप फ़ील्ड (type, code, message, doc_url, request_id, ...) त्रुटि मान पर रखता है।
import { BirdRateLimitError, BirdValidationError, BirdAPIError } from "@messagebird/sdk";
try {
await bird.email.send({
from: { email: "onboarding@messagebird.dev", name: "Bird" },
to: ["delivered@messagebird.dev"],
subject: "Hello from Bird",
html: "<p>My first Bird email.</p>",
});
} catch (err) {
if (err instanceof BirdRateLimitError) console.log(`rate limited; retry in ${err.retryAfter}s`);
else if (err instanceof BirdValidationError) console.error(err.details);
else if (err instanceof BirdAPIError) console.error(err.code, err.requestId);
else throw err;
}from bird import APIStatusError, RateLimitError, ValidationError
try:
client.email.send(
from_={"email": "onboarding@messagebird.dev", "name": "Bird"},
to=["delivered@messagebird.dev"],
subject="Hello from Bird",
text="My first Bird email.",
)
except RateLimitError as err:
print("rate limited; retry after", err.retry_after)
except ValidationError as err:
print(err.status_code, err.details)
except APIStatusError as err:
print(err.status_code, err.code, err.request_id)if err != nil {
var rle *bird.RateLimitError
var ve *bird.ValidationError
var ae *bird.APIError
switch {
case errors.As(err, &rle):
fmt.Println("rate limited; retry after", rle.RetryAfter)
case errors.As(err, &ve):
for _, d := range ve.Details {
fmt.Printf("%s: %s\n", d.Param, d.Message)
}
case errors.As(err, &ae):
fmt.Printf("API error %s (status %d, request %s)\n", ae.Code, ae.StatusCode, ae.RequestID)
default:
log.Print(err) // transport: *bird.ConnectionError or *bird.TimeoutError
}
}try {
$bird->email->send(
from: 'Bird <onboarding@messagebird.dev>',
to: ['delivered@messagebird.dev'],
subject: 'Hello from Bird',
html: '<p>My first Bird email.</p>',
);
} catch (ApiException $e) {
// The server returned an error response. $status is the HTTP status, $type
// the coarse category, $errorCode the stable E##### code.
echo $e->status, ' ', $e->errorCode ?? $e->type ?? 'error';
} catch (ConnectionException $e) {
// All retry attempts failed, so no HTTP response is available.
echo 'transport error: ', $e->getMessage();
}त्रुटि कैटलॉग
सार्वजनिक Bird API द्वारा लौटाया जाने वाला प्रत्येक त्रुटि कोड, प्रति कोड रेंज एक पेज में विभाजित। प्रत्येक रेंज पेज अपने कोड सूचीबद्ध करता है, और प्रत्येक कोड का अपना पेज है जिसमें कारण और समाधान दिया गया है। किसी भी त्रुटि प्रतिक्रिया पर doc_url सीधे उस कोड के पेज से लिंक करता है।
| रेंज | क्षेत्र | कोड |
|---|---|---|
E01xxx | इंफ्रास्ट्रक्चर | 30 कोड, 2 सेवानिवृत्त |
E02xxx | प्रमाणीकरण और पहचान | 24 कोड, 2 सेवानिवृत्त |
E03xxx | बिलिंग और प्लान | 15 कोड, 2 सेवानिवृत्त |
E04xxx | ईमेल भेजना और डिलीवरी | 87 कोड, 3 सेवानिवृत्त |
E05xxx | डोमेन और DNS | 19 कोड |
E06xxx | वेबहुक | 11 कोड |
E07xxx | वॉलेट | 4 कोड |
E08xxx | वर्कस्पेस और संगठन प्रबंधन | 1 कोड, 2 सेवानिवृत्त |
E10xxx | कोटा | 16 कोड, 2 सेवानिवृत्त |
E11xxx | IP पूल और डेडिकेटेड IP | 4 कोड, 1 सेवानिवृत्त |
E12xxx | SMS भेजना और डिलीवरी | 62 कोड, 5 सेवानिवृत्त |
E13xxx | Verify | 7 कोड, 1 सेवानिवृत्त |
E14xxx | नंबर | 6 कोड |
E15xxx | WhatsApp भेजना और डिलीवरी | 75 कोड |
E16xxx | भरोसा | 1 कोड |
E17xxx | एजेंट मेलबॉक्स | 16 कोड, 2 सेवानिवृत्त |
E19xxx | पंजीकरण अनुपालन | 6 कोड |
E20xxx | एसेट और मीडिया लाइब्रेरी | 15 कोड |
E21xxx | वॉइस और SIP ट्रंकिंग | 20 कोड, 9 सेवानिवृत्त |
E22xxx | नंबर लुकअप | 5 कोड |
E23xxx | रीयलटाइम | 1 कोड |
E24xxx | Competitive Insights | 6 कोड |
E25xxx | Sendability | 5 कोड, 1 सेवानिवृत्त |
E26xxx | eSIM | 19 कोड |
E27xxx | Inbox Insights | 9 कोड |
E28xxx | Apple Messages for Business | 48 कोड, 2 सेवानिवृत्त |
E32xxx | ऑपरेशन पुष्टि | 6 कोड |
E33xxx | संगठन पात्रता | 3 कोड, 1 सेवानिवृत्त |
E34xxx | कनेक्टर्स | 1 कोड, 1 सेवानिवृत्त |
संबंधित
- त्रुटि अवधारणाएँ: ब्रांचिंग रणनीति, वैलिडेशन विवरण, और
vendor_codeसिमेंटिक्स - प्रमाणीकरण:
401और403के पीछे के क्रेडेंशियल - Idempotency-Key हेडर:
409विरोध त्रुटियाँ और सुरक्षित फिर से प्रयास - दर सीमाएँ: नीतियाँ, हेडर, और
429को संभालना
संबंधित संसाधन
इस विषय के लिए दस्तावेज़, गाइड और उदाहरणों के साथ आगे बढ़ें।