Erreurs
Chaque échec lève une exception. Deux classes, et un id de requête sur chaque erreur d'API.
En attraper une
import { OpenEmailApiError, OpenEmailNetworkError, openemail } from '@openemail/sdk' try { await openemail.emails.send(message)} catch (error) { if (error instanceof OpenEmailApiError) { if (error.isValidation) console.error(error.code, error.param, error.message) if (error.isPermission) console.error(await openemail.addresses.list()) if (error.isRateLimited) console.error('try again in', error.retryAfterSeconds, 'seconds') console.error(error.status, error.requestId) } if (error instanceof OpenEmailNetworkError && error.isTimeout) console.error('no answer in time') throw error}Un permission_error sur un envoi vient généralement de la portée d'envoi de la CLÉ — un domaine ou une adresse qui ne lui a pas été accordé — plutôt que du workspace, et c'est pourquoi l'exemple affiche les adresses depuis lesquelles addresses.list() indique que cette clé peut envoyer.
Les classes
| Classe | Quand |
|---|---|
| `OpenEmailApiError` | L'API a répondu, et pas par un succès. Porte status, type, code, param, docUrl, requestId et retryAfterSeconds. |
| `OpenEmailNetworkError` | Aucune réponse n'est arrivée : DNS, TLS, une connexion coupée, le timeout, ou votre propre AbortSignal. Porte cause, et isTimeout vaut true quand le timeout en est la raison. |
| `Error` | Levée avant tout envoi : une clé manquante ou malformée, un baseUrl inutilisable, un navigateur, un id vide. |
| Getter | Vrai quand |
|---|---|
| `isAuth` | type vaut authentication_error, un 401 : aucune clé, un type d'identifiant erroné, ou une clé que nous n'avons pas émise. |
| `isPermission` | permission_error, un 403 : une vraie clé à laquelle manque la portée ou l'adresse From dont elle a besoin. |
| `isScopeMissing` | code vaut insufficient_scope, le 403 qui nomme une portée manquante. |
| `isInvalidRequest` | invalid_request_error, un 400 : une requête qui n'a pas pu être comprise. Un message dépassant le plafond de taille revient en 422 message_too_large : c'est donc isValidation qui l'attrape. |
| `isValidation` | validation_error, un 422 : le schéma l'a refusée, et param nomme le champ. |
| `isNotFound` | not_found_error, un 404 : la ressource n'existe pas. |
| `isConflict` | conflict_error, un 409 : la ressource a dépassé le stade où cette opération pouvait encore lui être appliquée. |
| `isRateLimited` | rate_limit_error, un 429. retryAfterSeconds contient le délai d'attente quand le serveur en a indiqué un. |
| `isServerError` | status vaut 500 ou plus. Citez requestId si vous contactez le support. |
| `isRetryable` | status vaut 408, 429, 500, 502, 503 ou 504. |
Les getters lisent type, la moitié figée de l'enveloppe. code reste une string, car l'API garantit qu'il est ouvert et additif : traitez donc un code que vous ne reconnaissez pas comme son type. Une union fermée ferait d'une mise à jour du SDK le prix à payer pour lire un nouveau mode d'échec.
Un corps qui n'est pas l'enveloppe d'erreur de l'API devient malgré tout une OpenEmailApiError, avec type déduit du statut et code fixé à unrecognised_response. Une réponse en succès dont le corps n'est pas du JSON en lève une également.
Une interruption est elle aussi une OpenEmailNetworkError, qu'elle survienne pendant la requête ou pendant l'attente précédant une retentative, et l'interruption est conservée sur cause. Vérifiez signal.aborted quand vous devez distinguer votre propre annulation d'une défaillance réseau.
requestId
Chaque OpenEmailApiError porte l'id de requête envoyé par le serveur, issu du corps de l'erreur ou de l'en-tête x-request-id, et c'est la seule chose qui relie votre échec à une ligne du journal du serveur. Une réponse en succès se résout au seul corps analysé : il n'y a donc pas d'id de requête à y lire.