त्रुटियाँ
एक ही आकार, दो स्तर, और हर चीज़ पर एक request id।
लिफ़ाफ़ा
type एक जमा हुआ समुच्चय है जिस पर आप शाखा बना सकते हैं और जो कभी बढ़ेगा नहीं। code विशिष्ट और वृद्धिशील है, इसलिए जिसे आप न पहचानें उसे उसके type की तरह बरतें। requestId हर प्रतिक्रिया पर होती है, सफलताओं पर भी, और वही किसी रिपोर्ट को किसी लॉग पंक्ति से जोड़ती है।
{ "error": { "type": "validation_error", "code": "invalid_email_address", "message": "Not a valid email address: ada@", "param": "to.0", "docUrl": "https://openemail.uk/docs/api/errors#invalid_email_address", "requestId": "req_e103790543af4…" }}param बिंदुओं और सूचकांकों के साथ आता है, इसलिए वह उसे रखने वाले फ़ील्ड के बजाय ठीक उसी तत्व की ओर इशारा करता है (to.0, attachments.2.filename)।
स्टेटस कोड
| स्थिति | type | सामान्य कोड |
|---|---|---|
| 400 | invalid_request_error | malformed_json, invalid_idempotency_key |
| 401 | authentication_error | missing_api_key, invalid_api_key, revoked_api_key, invalid_credential_type |
| 403 | permission_error | insufficient_scope, from_address_forbidden |
| 404 | not_found_error | resource_not_found |
| 409 | conflict_error | email_not_cancellable, translation_not_configured |
| 422 | validation_error | invalid_email_address, reserved_header, too_many_recipients, unknown_parameter, idempotency_key_reuse, label_not_directly_settable, unknown_language, translation_too_long |
| 429 | rate_limit_error | send_quota_exceeded, too_many_inboxes |
| 500 | api_error | internal_error |
| 503 | api_error | translation_failed |
404 कभी "मौजूद नहीं है" और "किसी दूसरे वर्कस्पेस का है" में फ़र्क नहीं करता। यह जानबूझकर है: यह फ़र्क ख़ुद एक जानकारी है।
429 कभी Retry-After नहीं भेजता, इसलिए अपनी प्रतीक्षा ख़ुद चुनें। send_quota_exceeded मासिक भेजाव भत्ता है और वह महीने की पहली तारीख़ को रीसेट होता है, इसलिए पीछे हटने के बजाय इसे किसी व्यक्ति को दिखाएँ। too_many_inboxes डिस्पोज़ेबल इनबॉक्स गढ़ने की ऊपरी सीमा है, और आपके पास पहले से मौजूद इनबॉक्स की अवधि बढ़ाने की उस पर कोई लागत नहीं है।
500 और 503 एक ही type साझा करते हैं और कॉलर के लिए अलग-अलग अर्थ रखते हैं। 503 का अर्थ है कोई निर्भरता जिसने उत्तर नहीं दिया (आज वह अनुवादक है), और अनुरोध को बिना बदले दोबारा आज़माना सार्थक है; 500 हमारी तरफ़ का है और उसे उसकी requestId के साथ रिपोर्ट करना सार्थक है।
इन्हें संभालना
व्यवहार के लिए type पर शाखा बनाएँ और जो संदेश आप किसी व्यक्ति को दिखाते हैं उसके लिए code पढ़ें। अपरिचित code आपके क्लाइंट में त्रुटि नहीं है। इसका अर्थ है कि हमने किसी विफलता को पहले से अधिक सटीक नाम दे दिया है।
const res = await fetch(`${BASE}/emails`, { method: 'POST', headers, body }); if (!res.ok) { const { error } = await res.json(); switch (error.type) { case 'rate_limit_error': throw new RateLimited(error.code); case 'validation_error': // error.param points at the offending field throw new BadRequest(`${error.param}: ${error.message}`); case 'authentication_error': // revoked_api_key and expired_api_key are worth telling an operator apart throw new AuthFailed(error.code); default: // quote requestId when you report it throw new Unexpected(error.message, error.requestId); }}