Hibák
Egy forma, két szint, és minden válaszon kérésazonosító.
A boríték
A type egy rögzített halmaz, amelyre elágazhatsz, és soha nem bővül. A code konkrét és bővülő, ezért egy fel nem ismert kódot kezelj a hozzá tartozó type-ként. A requestId minden válaszon ott van, a sikereseken is, és ez köti össze a hibajelentést egy naplósorral.
{ "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…" }}A param pontokkal tagolt és indexelt, így pontosan az elemre mutat (to.0, attachments.2.filename), nem az azt tartalmazó mezőre.
Állapotkódok
| Állapot | type | Gyakori kódok |
|---|---|---|
| 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 |
A 404 soha nem különbözteti meg a „nem létezik” esetet attól, hogy „egy másik munkaterülethez tartozik”. Ez szándékos: maga a különbség is információ.
A 429 soha nem tartalmaz Retry-After fejlécet, ezért a várakozási időt magad válaszd meg. A send_quota_exceeded a havi küldési keret, amely a hónap elsején nullázódik, ezért mutasd meg egy embernek, ahelyett hogy újrapróbálkoznál. A too_many_inboxes az eldobható postafiókok létrehozási plafonja, és egy már meglévő postafiók meghosszabbítása nem számít bele.
Az 500 és az 503 ugyanazt a type-ot használja, de a hívónak mást jelentenek. Az 503 egy függőség, amely nem válaszolt (jelenleg ez a fordító), és a kérést érdemes változatlanul újrapróbálni; az 500 a mi hibánk, és érdemes a requestId-val együtt jelenteni.
Kezelésük
A viselkedéshez a type alapján ágazz el, és a code-ot olvasd ki az emberi felhasználónak mutatott üzenethez. Egy fel nem ismert code nem hiba a kliensedben. Azt jelenti, hogy egy hibát pontosabban neveztünk meg, mint korábban.
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); }}