Errores
Esta guía resume cómo responde la API cuando algo falla. El OpenAPI actual no documenta schemas de response, así que esta es la referencia práctica mientras backend completa esa parte.
Formato de respuesta
La API usa dos variantes principales:
- simple:
{ "error": "<mensaje>" } - con código:
{ "error": "<mensaje>", "error_code": "<CODE>", "retry_after": <seg> }
Códigos HTTP usados
| Código | Nombre | Uso típico |
|---|---|---|
| 200 | OK | Operación exitosa |
| 400 | Bad Request | Validación o request inválida |
| 401 | Unauthorized | Auth inválida o expirada |
| 403 | Forbidden | Usuario deshabilitado o cuenta bloqueada |
| 404 | Not Found | Recurso inexistente |
| 429 | Too Many Requests | Rate limit excedido |
| 500 | Internal Server Error | Error inesperado de backend |
| 503 | Service Unavailable | Servicio temporalmente no disponible |
Códigos de error conocidos
| error_code | Contexto |
|---|---|
RATE_LIMIT_USER | Límite por usuario excedido |
RATE_LIMIT_IP | Límite por IP excedido |
ACCOUNT_LOCKED | Cuenta bloqueada por seguridad |
Cómo manejar errores comunes
401 con token JWT
Intentá renovar con Autenticación. Si el refresh también falla, redirigí a login.
429
Leé Retry-After, esperá y reintentá. Ver Rate limits.
5xx
Usá reintento con backoff exponencial y poné un límite de intentos. No insistas indefinidamente.