Manejo de Errores
La API usa códigos de respuesta HTTP convencionales para indicar el éxito o fracaso de las solicitudes. Esta página documenta formatos de error y estrategias de manejo.
Formato de Respuesta de Error
Todas las respuestas de error siguen una estructura JSON consistente:
{
"error": "VALIDATION_ERROR",
"message": "Invalid request parameters",
"timestamp": "2026-07-10T12:00:00Z",
"path": "/api/v1/assets",
"details": [{ "field": "size", "message": "must be at most 100" }]
}| Campo | Descripción |
|---|---|
| error | Código de error legible por máquina |
| message | Descripción del error legible por humanos |
| timestamp | Cuándo ocurrió el error |
| path | La ruta del endpoint solicitado |
| details | Detalles adicionales para errores de validación (opcional) |
Códigos de Estado HTTP
| Código | Descripción |
|---|---|
| 400 | Parámetros de solicitud inválidos o cuerpo de solicitud malformado |
| 401 | Clave API faltante o inválida |
| 403 | La clave API no tiene los permisos requeridos para este endpoint |
| 404 | El recurso solicitado no existe |
| 429 | Límite de velocidad excedido - reintenta después del tiempo especificado |
| 500 | Error interno del servidor - contacta soporte si persiste |
| 503 | Servicio temporalmente no disponible - intenta de nuevo más tarde |
Estrategia de Reintento
Para errores transitorios, implementa una estrategia de reintento con retroceso exponencial:
- Para errores 429, espera el tiempo especificado en el encabezado X-RateLimit-Reset antes de reintentar
- Para errores 5xx, usa retroceso exponencial (1s, 2s, 4s, 8s...) con variación
- Establece un conteo máximo de reintentos (ej. 3-5 intentos) para evitar bucles infinitos
Limitación de Velocidad
Cuando excedes el límite de velocidad, la API devuelve un código de estado 429 con detalles sobre cuándo puedes reintentar:
Usa el campo retryAfter o el encabezado X-RateLimit-Reset para determinar cuándo reintentar tu solicitud.
Errores de Validación
Para errores 400, la respuesta incluye un array de detalles con errores específicos por campo:
Mejores Prácticas de Manejo de Errores
- Siempre verifica el código de estado HTTP antes de parsear el cuerpo de la respuesta
- Implementa retroceso exponencial para errores 429 y 5xx
- Registra errores con la marca de tiempo y ruta para depuración
- Maneja códigos de error específicos de manera diferente (ej. 401 activa re-autenticación)