Kļūdas
Viena forma, divi līmeņi un pieprasījuma id pie visa.
Aploksne
type ir iesaldēta kopa, pēc kuras var zaroties, un tā nekad neaugs. code ir konkrēts un papildināms, tāpēc pret neatpazītu izturieties kā pret tā type. requestId ir katrā atbildē, ieskaitot veiksmīgās, un tas ir tas, kas sasaista ziņojumu ar žurnāla rindu.
{ "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 ir ar punktiem un indeksiem, tāpēc tas norāda uz tieši to elementu (to.0, attachments.2.filename), nevis uz lauku, kas to satur.
Statusa kodi
| Statuss | type | Biežākie kodi |
|---|---|---|
| 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 nekad nešķir "neeksistē" no "pieder citai darbvietai". Tas ir apzināti: šī atšķirība pati par sevi ir informācija.
429 nekad nenes Retry-After, tāpēc gaidīšanas laiku izvēlieties paši. send_quota_exceeded ir mēneša sūtīšanas limits, un tas atjaunojas mēneša pirmajā datumā, tāpēc parādiet to cilvēkam, nevis atkāpieties ar aizturi. too_many_inboxes ir vienreizlietojamo iesūtņu izveides griesti, un jau esošas iesūtnes pagarināšana pret tiem neko nemaksā.
500 un 503 dala vienu type un izsaucējam nozīmē dažādas lietas. 503 ir atkarība, kas neatbildēja (šodien tas ir tulkotājs), un pieprasījumu ir vērts atkārtot nemainītu; 500 ir mūsu, un to ir vērts paziņot kopā ar tā requestId.
Kā ar tām rīkoties
Zarojiet pēc type, lai izlemtu par rīcību, un lasiet code, lai izvēlētos ziņojumu, ko rādāt cilvēkam. Neatpazīts code nav kļūda jūsu klientā. Tas nozīmē, ka esam nosaukuši kļūmi precīzāk nekā agrāk.
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); }}