त्रुटि प्रतिक्रियाएँ
हर विफल अनुरोध एक ही 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 | हाँ | मोटी ब्रांचिंग के लिए व्यापक श्रेणी: एक बंद enum (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 | अनुरोध को प्रोसेस करते समय हमारी तरफ़ कुछ विफल हो गया। देखें Idempotency। |
| 501 | not_implemented_error | यह endpoint 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 | Auth और पहचान | 9 कोड, 2 सेवानिवृत्त |
| E03xxx | बिलिंग और योजनाएँ | 12 कोड |
| E04xxx | ईमेल भेजना और डिलीवरी | 67 कोड, 3 सेवानिवृत्त |
| E05xxx | डोमेन और DNS | 19 कोड |
| E06xxx | Webhooks | 7 कोड |
| E07xxx | Wallet | 4 कोड |
| E10xxx | कोटा | 9 कोड, 2 सेवानिवृत्त |
| E11xxx | IP पूल और डेडिकेटेड IP | 4 कोड, 1 सेवानिवृत्त |
| E12xxx | SMS भेजना और डिलीवरी | 49 कोड, 5 सेवानिवृत्त |
| E13xxx | Verify | 7 कोड, 1 सेवानिवृत्त |
| E14xxx | नंबर | 5 कोड |
| E15xxx | WhatsApp भेजना और डिलीवरी | 49 कोड |
| E16xxx | Trust | 1 कोड |
| E17xxx | एजेंट मेलबॉक्स | 14 कोड, 2 सेवानिवृत्त |
| E19xxx | पंजीकरण अनुपालन | 4 कोड |
| E21xxx | वॉइस और SIP ट्रंकिंग | 16 कोड, 7 सेवानिवृत्त |
| E22xxx | नंबर लुकअप | 4 कोड |
| E23xxx | Realtime | 1 कोड |
| E24xxx | Competitive Insights | 6 कोड |
| E25xxx | Sendability | 5 कोड, 1 सेवानिवृत्त |
| E27xxx | Inbox Insights | 5 कोड |
| E28xxx | Apple Messages for Business | 18 कोड, 2 सेवानिवृत्त |
| E32xxx | ऑपरेशन पुष्टि | 6 कोड |
संबंधित
- त्रुटि अवधारणाएँ: ब्रांचिंग रणनीति, वैलिडेशन विवरण, और vendor_code सिमेंटिक्स
- प्रमाणीकरण: 401 और 403 के पीछे के क्रेडेंशियल
- Idempotency-Key हेडर: 409 विरोध त्रुटियाँ और सुरक्षित फिर से प्रयास
- अनुरोध दर सीमाएँ: नीतियाँ, हेडर, और 429 को संभालना
संबंधित संसाधन
इस विषय के लिए डॉक्यूमेंटेशन, गाइड और उदाहरणों के साथ आगे बढ़ें। संसाधन अंग्रेज़ी में हैं।
कॉन्सेप्ट समझेंShould I use a Bird SDK or call the API directly?लर्निंग पाथ फ़ॉलो करेंBuild your first integrationइम्प्लीमेंटेशन गाइडSend your first email
इम्प्लीमेंटेशन ब्रीफ़ पाएँ