Errores
Todo fallo lanza una excepción. Dos clases, y un id de solicitud en cada error de la API.
Capturar uno
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 en un envío suele deberse al alcance de envío de la CLAVE, a un dominio o a una dirección que no se le concedió, y no al espacio de trabajo, y por eso el ejemplo imprime lo que dice addresses.list() sobre las direcciones con las que puede enviar esta clave.
Las clases
| Clase | Cuándo |
|---|---|
| `OpenEmailApiError` | La API respondió, y no con un éxito. Lleva status, type, code, param, docUrl, requestId y retryAfterSeconds. |
| `OpenEmailNetworkError` | No llegó ninguna respuesta: DNS, TLS, una conexión caída, el tiempo de espera o tu propio AbortSignal. Lleva cause, e isTimeout es true cuando el motivo fue el tiempo de espera. |
| `Error` | Se lanza antes de enviar nada: una clave ausente o mal formada, un baseUrl inutilizable, un navegador, un id vacío. |
| Getter | True cuando |
|---|---|
| `isAuth` | type es authentication_error, un 401: sin clave, un tipo de credencial equivocado o una clave que no emitimos nosotros. |
| `isPermission` | permission_error, un 403: una clave real sin el scope o sin la dirección From que necesita. |
| `isScopeMissing` | code es insufficient_scope, el 403 que nombra un scope que falta. |
| `isInvalidRequest` | invalid_request_error, un 400: una solicitud que no se pudo entender. Un mensaje que supera el límite de tamaño vuelve como un 422 message_too_large, así que isValidation es el getter que lo captura. |
| `isValidation` | validation_error, un 422: el esquema lo rechazó, y param nombra el campo. |
| `isNotFound` | not_found_error, un 404: no existe ese recurso. |
| `isConflict` | conflict_error, un 409: el recurso ha pasado el punto en el que se le podía hacer esto. |
| `isRateLimited` | rate_limit_error, un 429. retryAfterSeconds contiene la espera cuando el servidor indicó una. |
| `isServerError` | status es 500 o superior. Cita requestId si contactas con soporte. |
| `isRetryable` | status es 408, 429, 500, 502, 503 o 504. |
Los getters leen type, la mitad congelada del sobre. code sigue siendo un string, porque la API garantiza que es abierto y aditivo, así que trata uno que no reconozcas según su type. Una unión cerrada convertiría una actualización del SDK en el precio de leer un nuevo modo de fallo.
Un cuerpo que no es el sobre de error de la API se convierte igualmente en un OpenEmailApiError, con type inferido a partir del status y code fijado en unrecognised_response. Una respuesta correcta cuyo cuerpo no sea JSON también lanza uno.
Un aborto también es un OpenEmailNetworkError, tanto si ocurre durante la solicitud como durante la espera previa a un reintento, y el aborto se conserva en cause. Comprueba signal.aborted cuando necesites distinguir tu propia cancelación de un fallo de red.
requestId
Todo OpenEmailApiError lleva el id de solicitud que envió el servidor, tomado del cuerpo del error o de la cabecera x-request-id, y es lo único que ata tu fallo a una línea del registro del servidor. Una respuesta correcta se resuelve solo en el cuerpo analizado, así que en ella no hay ningún id de solicitud que leer.