Errores y reintentos
Una clase de excepción para cada clase de rechazo y reintentos que no pueden enviar dos veces.
Gestionar un error
try { client.templates().send("order-shipped", Body.of( "from", "[email protected]", "to", "[email protected]", "props", Body.of("orderId", "AC-4192") ));} catch (ValidationException error) { System.err.println(error.param() + " " + error.getMessage());} catch (RateLimitException error) { System.err.println("Wait " + error.retryAfterSeconds() + " seconds");} catch (ApiException error) { System.err.println(error.status() + " " + error.code() + " " + error.requestId());} catch (NetworkException error) { System.err.println(error.isTimeout() ? "Timed out" : "No response");}Un rechazo de la API lanza una ApiException, o la subclase correspondiente a su tipo, con lo que la API dijo al respecto. Toda excepción que lanza el cliente es una OpenEmailException no comprobada, así que un solo catch las cubre todas.
| Método | Qué contiene |
|---|---|
| status() | El estado HTTP, o 0 cuando no llegó ninguna respuesta. |
| type(), 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. |
| 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
| Excepción | Cuándo se lanza |
|---|---|
| AuthenticationException | La clave o el token fue rechazado, con un 401. |
| PermissionException | La credencial no puede hacer esto, con un 403. |
| NotFoundException | Nada tiene ese id, con un 404. |
| ConflictException | El cambio entra en conflicto con el estado actual, con un 409. |
| ValidationException | Se rechazó un campo, con un 422. |
| RateLimitException | Demasiadas peticiones, o una cuota está agotada, con un 429. |
| InvalidRequestException | Cualquier otro rechazo de la petición. |
| ApiException | La API falló, con un estado de 500 o superior. |
| NetworkException | No llegó ninguna respuesta. |
| IllegalArgumentException | La propia llamada era incorrecta, y no se envió nada. |
| WebhookSignatureException | Una entrega de webhook no superó su comprobación. |
Una ApiException también responde preguntas sobre sí misma: isValidation(), isNotFound(), isRateLimited(), isServerError() e isRetryable(), con isScopeMissing() cuando a la credencial le falta el ámbito que necesita la llamada e isStepUpRequired() cuando un token de acceso tiene que verificar antes un código. NetworkException.isTimeout() indica que venció el plazo.
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.