Errores y códigos de estado
Los errores son JSON, siempre con la misma forma, y siempre llevan un código estable legible por máquina. Ramifica según el código, no según el mensaje.
La forma
Todo fallo devuelve un objeto con un error legible por personas y un code estable. El mensaje está escrito para una persona y puede reformularse; el código es un contrato y no cambiará a tus espaldas.
{
"error": "That file is larger than the 200 MB limit on your plan.",
"code": "VALIDATION_FAILED"
}Códigos que deberías manejar
| Código | HTTP | Qué significa |
|---|---|---|
| NOT_AUTHENTICATED | 401 | Token bearer ausente o mal formado |
| FORBIDDEN | 403 | La clave es válida pero no tiene permiso para esto |
| NOT_ENTITLED | 402 | El plan de la cuenta no incluye acceso a la API |
| VALIDATION_FAILED | 400 / 413 | Petición incorrecta, conversión no admitida o archivo demasiado grande |
| NOT_FOUND | 404 | No existe ese trabajo, o pertenece a otra cuenta |
| RATE_LIMITED | 429 | Límite por hora alcanzado. Espera y reinténtalo. |
| INTERNAL | 500 | Algo se rompió por nuestra parte. Es seguro reintentar. |
Qué conviene reintentar
429 y 500 conviene reintentarlos, con una espera: retrocede en vez de dar vueltas en bucle, porque los reintentos cuentan para tu límite por hora igual que cualquier otra petición.
Todo lo demás es permanente para esa petición. Reintentar un 400, un 402 o un 404 produce la misma respuesta y gasta tu límite en averiguarlo.
Un 502 o 503 sin cuerpo JSON no viene de la aplicación: es el proxy que hay delante, y ahí siempre merece la pena reintentar.