Errores
Todo fallo lanza una excepción. Dos clases, y un id de solicitud en cada error de la API.
Capturar uno
from openemail import OpenEmailApiError, OpenEmailNetworkError, openemail try: openemail.emails.send({'from': sender, 'to': recipient, 'subject': subject, 'text': text})except OpenEmailApiError as error: if error.is_validation: print(error.code, error.param, error.message) if error.is_permission: print(openemail.addresses.list()) if error.is_rate_limited: print('try again in', error.retry_after_seconds, 'seconds') print(error.status, error.request_id) raiseexcept OpenEmailNetworkError as error: if error.is_timeout: print('no answer in time') raiseUn 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 message, status, type, code, param, doc_url, request_id, retry_after_seconds, fields y body. |
| OpenEmailNetworkError | No llegó ninguna respuesta: DNS, TLS, una conexión caída o el tiempo de espera. Lleva cause, la excepción subyacente de httpx, e is_timeout es True cuando el motivo fue el tiempo de espera. |
| OpenEmailError | La base de ambas, así que un solo except captura cualquier fallo causado por la API o por la red. WebhookVerificationError, que lanza verify_webhook_signature, también hereda de ella. |
| ValueError | Se lanza antes de enviar nada: una clave ausente o mal formada, un base_url inutilizable, una credencial con destino a http sin cifrar, un id vacío. Un http_client equivocado, o un cuerpo que JSON no puede representar, lanza TypeError en su lugar. |
fields enumera cada respuesta que rechazó un formulario de suscripción, como key y error, y es None en cualquier otro error. body conserva el JSON que envió la API, o None cuando el cuerpo no era JSON.
| Propiedad | True cuando |
|---|---|
| is_auth | type es authentication_error, un 401: sin clave, un tipo de credencial equivocado o una clave que no emitimos nosotros. |
| is_permission | permission_error, un 403: una clave real sin el scope o sin la dirección From que necesita. |
| is_scope_missing | code es insufficient_scope, el 403 que nombra un scope que falta. |
| is_invalid_request | 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 is_validation es la propiedad que lo captura. |
| is_validation | validation_error, un 422: el esquema lo rechazó, y param nombra el campo. |
| is_not_found | not_found_error, un 404: no existe ese recurso. |
| is_conflict | conflict_error, un 409: el recurso ha pasado el punto en el que se le podía hacer esto. |
| is_rate_limited | rate_limit_error, un 429. retry_after_seconds contiene la espera cuando el servidor indicó una. |
| is_server_error | status es 500 o superior. Cita request_id si contactas con soporte. |
| is_retryable | status es 408, 429, 500, 502, 503 o 504. |
| is_step_up_required | code es step_up_required, el 403 que recibe un token de acceso OAuth antes de un cambio delicado hasta que la persona haya verificado un código. |
La mayoría de las propiedades leen type, la mitad congelada del sobre. code sigue siendo un str, porque la API garantiza que es abierto y aditivo, así que trata uno que no reconozcas según su type. Un Literal cerrado 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 código de estado y code fijado en unrecognised_response. Una respuesta correcta cuyo cuerpo no sea JSON también lanza uno.
Cancelar una llamada de AsyncOpenEmail no lanza ningún OpenEmailError. Se propaga la propia cancelación, tanto si ocurre durante la solicitud como durante la espera previa a un reintento, y después no se reintenta nada.
request_id
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 vincula tu fallo con una línea del registro del servidor. Una respuesta correcta devuelve solo el cuerpo analizado, así que en ella no hay ningún id de solicitud que leer.
str(error) termina con el estado, el código y el id de solicitud, así que una línea de registro que imprima la excepción conserva los tres. Un OpenEmailApiError también se puede serializar con pickle sin perder ningún campo, así que uno lanzado en un proceso worker llega intacto al proceso padre.