Formato de los errores
Todos los errores devuelven el mismo cuerpo, con el código HTTP correspondiente:
{
"error": {
"code": "invalid_request",
"message": "Los parámetros de la petición no son válidos.",
"details": [
{ "field": "month", "message": "Number must be less than or equal to 12" }
]
}
}El campo details solo aparece en los errores de validación e indica exactamente qué
campo falla.
Códigos
| HTTP | code | Qué significa y qué hacer |
|---|---|---|
| 400 | invalid_request | Falta un parámetro o tiene un formato incorrecto. Mira details. |
| 401 | unauthorized | Token ausente, mal formado, caducado o revocado. Genera uno nuevo. |
| 403 | forbidden | El token no tiene el permiso necesario, normalmente write. |
| 404 | not_found | El recurso no existe o no es tuyo. La API no distingue entre ambos casos. |
| 429 | rate_limited | Has superado el límite de peticiones. Espera y reintenta. |
| 500 | internal_error | Fallo del servidor. Reintenta; si persiste, escríbenos. |
Un 404 en un recurso que sabes que existe casi siempre significa que pertenece a otra
cuenta. Es intencionado: la API nunca confirma la existencia de datos ajenos.
Límite de peticiones
120 peticiones por minuto y token, en ventanas fijas de un minuto.
Cada respuesta incluye el estado del contador:
| Cabecera | Contenido |
|---|---|
X-RateLimit-Limit | Peticiones permitidas por ventana. |
X-RateLimit-Remaining | Peticiones que te quedan en la ventana actual. |
X-RateLimit-Reset | Marca de tiempo Unix en la que se reinicia el contador. |
Al pasarte recibes un 429 con una cabecera Retry-After en segundos:
HTTP/1.1 429 Too Many Requests
Retry-After: 23La forma correcta de reaccionar es esperar los segundos que indique Retry-After y
reintentar, no reintentar de inmediato en bucle.
Buenas prácticas
Pide totales, no listas. Si necesitas cuánto gastaste en marzo, usa /v1/summary
en lugar de descargar todos los apuntes y sumarlos tú.
Pagina. Los listados devuelven 50 elementos por defecto y 200 como máximo. Usa
has_more de la respuesta para saber si quedan más.
Cachea lo que no cambia. Las categorías y los índices de mercado no cambian de un minuto a otro.