Errors
Una sola forma, dos nivells i un id de petició a tot arreu.
El sobre
type és un conjunt tancat sobre el qual podeu ramificar i que no creixerà mai. code és específic i additiu, així que tracteu-ne un que no reconegueu com el seu type. requestId és a totes les respostes, incloses les correctes, i és el que lliga un informe amb una línia de registre.
{ "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 va amb punts i índexs, de manera que assenyala l'element exacte (to.0, attachments.2.filename) i no el camp que el conté.
Codis d'estat
| Estat | type | Codis habituals |
|---|---|---|
| 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 |
Un 404 no distingeix mai «no existeix» de «pertany a un altre espai de treball». És deliberat: la diferència ja és informació per si mateixa.
Un 429 no porta mai Retry-After, així que trieu vosaltres l'espera. send_quota_exceeded és l'assignació mensual d'enviaments i es reinicia el dia u de cada mes, així que mostreu-ho a una persona en lloc d'aplicar una espera progressiva. too_many_inboxes és el sostre de creació de bústies d'un sol ús, i ampliar una bústia que ja teniu no hi compta gens.
500 i 503 comparteixen type i volen dir coses diferents per a qui crida. Un 503 és una dependència que no ha respost (avui, el traductor), i val la pena reintentar la petició sense canvis; un 500 és nostre i val la pena informar-ne amb el seu requestId.
Com tractar-los
Ramifiqueu sobre type per al comportament i llegiu code per al missatge que mostreu a una persona. Un code no reconegut no és cap error del vostre client. Vol dir que hem anomenat una fallada amb més precisió que abans.
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); }}