Errores y reintentos
Un único tipo de excepción para cada rechazo, una propiedad para cada clase y reintentos que no pueden enviar dos veces.
Gestionar un error
try{ await client.Emails.SendAsync(new Body { ["from"] = "[email protected]", ["to"] = "[email protected]", ["subject"] = "Your September invoice", ["text"] = "Invoice attached.", });}catch (OpenEmailApiException error) when (error.IsValidation){ Console.Error.WriteLine($"{error.Code} {error.Param} {error.Message}");}catch (OpenEmailApiException error) when (error.IsRateLimited){ Console.Error.WriteLine($"try again in {error.RetryAfterSeconds} seconds");}catch (OpenEmailNetworkException error) when (error.IsTimeout){ Console.Error.WriteLine("no answer in time");}Un rechazo de la API lanza OpenEmailApiException, y la ausencia total de respuesta lanza OpenEmailNetworkException. Ambas derivan de OpenEmailException, así que un solo catch captura cualquiera de las dos, y un filtro when elige la clase.
| Propiedad | Qué contiene |
|---|---|
| Status | El status HTTP. |
| ErrorType, Code | El tipo de error y el código de la API, como validation_error e invalid_parameter. |
| Param | El campo culpable, cuando lo hay. |
| RequestId | El id que debes citar cuando escribas a soporte. |
| DocUrl | La página de la documentación que explica el código. |
| RetryAfterSeconds | Cuánto te pidió la API que esperaras, en segundos. |
| Fields | Los campos que rechazó un formulario de suscripción, cada uno con una key y un error. |
| Body | El cuerpo de la respuesta, decodificado. |
Las clases de fallo
| Propiedad | Cuándo es verdadera |
|---|---|
| IsAuth | La clave o el token fue rechazado, con un 401. |
| IsPermission | La credencial no puede hacer esto, con un 403. |
| IsScopeMissing | A la credencial le falta el ámbito que la llamada necesita. |
| IsStepUpRequired | Un token de acceso tiene que verificar antes un código. |
| IsNotFound | Nada tiene ese id, con un 404. |
| IsConflict | El cambio entra en conflicto con el estado actual, con un 409. |
| IsValidation | Se rechazó un campo, con un 422. |
| IsRateLimited | Demasiadas peticiones, o una cuota está agotada, con un 429. |
| IsInvalidRequest | Cualquier otro rechazo de la petición. |
| IsServerError | La API falló, con un estado de 500 o superior. |
| IsRetryable | El estado es uno de los que el cliente reintenta. |
| IsTimeout | No llegó ninguna respuesta antes de que venciera el tiempo de espera. Esta está en OpenEmailNetworkException. |
Un error en la propia llamada, como una clave mal formada o un id vacío, lanza ArgumentException antes de que se envíe nada. Un token cancelado lanza OperationCanceledException, y una entrega de webhook que no supera su comprobación lanza OpenEmailWebhookException.
Un código de verificación
Un token de acceso actúa en nombre de una persona, así que antes de un cambio delicado, como eliminar un dominio, se le pide el mismo código de verificación que pide la app web. Pide un código, compruébalo y vuelve a hacer la petición. A las claves de API nunca se les pide uno.
var domainId = "b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f"; try{ await client.Domains.DeleteAsync(domainId);}catch (OpenEmailApiException error) when (error.IsStepUpRequired){ var challenge = await client.Security.BeginStepUpAsync(); Console.WriteLine($"Enter the code sent by {challenge["method"]}"); await client.Security.VerifyStepUpAsync(new Body { ["code"] = Console.ReadLine()?.Trim() }); await client.Domains.DeleteAsync(domainId);}Lo que se reintenta
- Las lecturas, los envíos y toda escritura que es seguro repetir se reintentan, hasta
MaxRetriesveces. Cualquier otra escritura se envía una sola vez. - Los estados 408, 500, 502, 503 y 504 se reintentan con una espera que empieza en medio segundo y se duplica hasta ocho segundos.
- Un 429 se reintenta solo cuando lleva un
Retry-Afterde un minuto o menos, y el cliente espera ese tiempo. - Una conexión que falla o que agota el tiempo de espera se reintenta del mismo modo.
Un envío que se reintenta lleva siempre la misma clave de idempotencia, así que la API reproduce el primer mensaje en vez de enviar un segundo.