Errores y límites
Errores y límites
El mismo formato en todos los fallos, y los códigos que puede dar hoy /v1/dev/*.
El formato de un error
Todo fallo contesta en JSON, con un código estable para el programa y un mensaje en castellano para quien lo lea:
{
"codigo": "clave_invalida",
"mensaje": "Esa clave de API no existe o ha sido revocada."
}Los códigos de hoy
cuerpo_de_validacionUn parámetro no tiene la forma que pide el endpoint (p. ej. una fecha que no es AAAA-MM-DD).
no_autenticadoFalta la cabecera Authorization con la clave de API.
clave_invalidaLa clave no existe, está mal escrita o ha sido revocada.
clave_ip_no_permitidaLa clave lleva una lista blanca de IPs/CIDR (Configuración › API) y la petición no viene de ninguna de ellas. La clave en sí es válida: lo que falla es desde dónde se usa.
no_encontradoLa empresa, la persona o el día pedido no están en lo que tenemos cargado del BORME.
—La ruta no existe todavía en tu entorno: la plataforma se abre por fases.
demasiadas_peticionesSe ha superado el límite de la clave. La cabecera Retry-After dice, en segundos, cuándo volver a intentarlo.
Límite de peticiones
Cada clave de API puede hacer 120 llamadas por minuto a /v1/dev/* (el mismo límite que usa, para las mismas consultas, la app móvil de Jurilia). Toda respuesta lleva tres cabeceras para seguir el consumo sin tener que provocar un 429:
X-RateLimit-LimitEl tope de la ventana actual: 120.
X-RateLimit-RemainingCuántas llamadas quedan en esta ventana de un minuto.
X-RateLimit-ResetCuándo se reinicia la ventana, como instante Unix (segundos).
Restricción por IP/CIDR
Es aparte del límite de peticiones, y opcional: desde Configuración › API puedes restringir cada clave a una lista de IPs o redes (formato CIDR, IPv4 o IPv6). Vacía —lo normal— significa sin restricción; con la lista puesta, una llamada desde fuera de ella da 403, aunque la clave sea válida.
Límites por plan
Hoy el límite es el mismo para toda clave activa: no hay todavía planes de pago con límites distintos por nivel. Si eso cambia, se anuncia aquí antes de aplicarse — no antes.