Manejo de errores
Códigos de error y cómo manejarlos
Todas las respuestas de error tienen este formato:
json
{
"error": {
"code": "machine_readable_code",
"message": "Human-readable description in English."
}
}Códigos comunes
| Status | Código | Significado | |
|---|---|---|---|
| 400 | invalid_request | — | Body inválido o campos malformados. |
| 401 | unauthorized | — | API key faltante, inválida o revocada. |
| 402 | quota_exceeded | — | Sin storage suficiente. |
| 403 | forbidden | — | Key sin scope requerido. |
| 403 | plan_restricted | — | Feature requiere plan superior. |
| 404 | not_found | — | Recurso no existe o no es tuyo. |
| 429 | rate_limited | — | Demasiados requests. Respetá Retry-After. |
| 500 | internal_error | — | Error nuestro. Reintentá con backoff. |
Política de retry
Recomendaciones de retry según el status:
- 4xx (excepto 429): NO reintentes. El error es permanente hasta que cambies algo (corregir body, generar key nueva, comprar más storage).
- 429: respetá el header Retry-After. Implementá backoff exponencial.
- 5xx: reintentá con backoff (1s, 2s, 4s, 8s, 16s). Si persiste >5 min, abrí ticket.
Recomendado: loguear el code (machine-readable) en tu sistema, no el message. Los mensajes están en inglés y pueden cambiar; los códigos son estables.