Portal del desarrollador · en preparación

Límites y errores

Qué te dice la API sobre tu consumo, cómo se ven los errores y qué reintentar. Programa contra el código, no contra el texto.

Límites

Cada respuesta dice cuánto te queda

Cabeceras de límites y de seguimiento
Cabecera	Contenido
`X-RateLimit-Limit`	Llamadas permitidas por minuto. Todas las respuestas de una clave válida las llevan (los errores también).
`X-RateLimit-Remaining`	Llamadas que quedan en la ventana del minuto.
`X-RateLimit-Reset`	Instante, en segundos desde 1970, en que se reinicia la ventana del minuto.
`X-Monthly-Limit`	Cupo de llamadas del mes.
`X-Monthly-Remaining`	Cupo que queda del mes. Una llamada rechazada no gasta cupo ni se cobra.
`X-Request-Id`	Identificador de la petición (el mismo que `request_id` del cuerpo). Guárdalo si pides soporte.

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1790575260
X-Monthly-Limit: 100000
X-Monthly-Remaining: 99412

Si te pasas, 429 con Retry-After. Nunca se cobra por exceso y una llamada rechazada no gasta cupo.
Reintenta con espera creciente y respeta Retry-After. Solo se reintentan los 429 y los 5xx.
Con una clave de pruebas (erj_test_) no se gasta el cupo mensual, pero sí se limita por minuto.
Las librerías cliente leen estas cabeceras tras cada respuesta y reintentan solas las lecturas.

Errores

Errores con forma de RFC 9457

Los errores de la API llevan los campos de RFC 9457 y la cabecera X-Request-Id. Se envían conContent-Type: application/json, noapplication/problem+json. Programa contra code, no contra title, y guardarequest_id por si pides soporte.

Las rutas de OAuth responden con la forma de RFC 6749 (error, error_description): están en la referencia.

{
  "type": "https://api.elregistrodejornada.com/errores/ambito_insuficiente",
  "title": "Sin permiso",
  "status": 403,
  "detail": "La clave no tiene el ámbito «fichajes:leer».",
  "code": "ambito_insuficiente",
  "request_id": "req_8f2c..."
}

Códigos de error de la API
Estado	Código	Cuándo
400	`parametro_invalido`	Un parámetro de consulta está fuera de rango, mal escrito o no existe.
400	`cursor_invalido`	El cursor no es válido o se usó con otros filtros.
400	`cuerpo_invalido`	Ver la referencia.
401	`clave_ausente`	La petición no lleva la cabecera Authorization con la clave.
401	`clave_invalida`	La clave no existe o está mal escrita.
401	`clave_revocada`	La clave se revocó desde la aplicación.
401	`clave_caducada`	La clave pasó su fecha de caducidad.
403	`clave_ip_no_permitida`	La clave tiene una lista de IP y la petición viene de otra.
403	`ambito_insuficiente`	La clave no tiene el ámbito que pide la ruta.
403	`empresa_inactiva`	La empresa de la clave no está activa.
403	`complemento_no_contratado`	Ver la referencia.
404	`recurso_no_encontrado`	La ruta no existe.
404	`persona_no_encontrada`	No hay esa persona en tu empresa.
404	`centro_no_encontrado`	No hay ese centro en tu empresa.
404	`modificacion_no_encontrada`	No hay ese expediente de modificación en tu empresa.
404	`informe_no_encontrado`	No hay ese informe en tu empresa.
405	`metodo_no_permitido`	Se usó un método que esa ruta no admite. La respuesta trae Allow con los que sí (GET, OPTIONS; y POST en las rutas de escritura y de cálculo).
422	`rango_demasiado_amplio`	El intervalo de fechas supera el máximo de la ruta (31 días en fichajes e incidencias; 93 en calendario).
429	`limite_por_minuto_excedido`	Superaste las llamadas por minuto de la clave. Trae Retry-After.
429	`limite_mensual_excedido`	Agotaste el cupo del mes. Trae Retry-After. Nunca se cobra por exceso.
429	`demasiados_fallos_de_autenticacion`	Diez fallos de autenticación en diez minutos desde el mismo origen: bloqueo de 15 minutos. Trae Retry-After.
503	`flujo_sin_configurar`	El flujo de eventos no está disponible en este momento (solo GET /eventos).

Antes de llegar a la API

Hay otra forma de error

Lo que ocurre antes de llegar a la API (la capa HTTP) responde con otra forma:ok, error y mensaje. Trata cualquier error con una forma que no reconozcas como genérico y reintenta los 429 y los 5xx.

{
  "ok": false,
  "error": "demasiadas_peticiones",
  "mensaje": "..."
}

Errores de la capa HTTP
Estado	`error`	Cuándo
429	`demasiadas_peticiones`	Más de 300 llamadas por minuto desde la misma IP, antes de mirar la clave. Trae Retry-After.
403	`origen_no_permitido`	Solo desde páginas de otro origen en un navegador.
413	`cuerpo_demasiado_grande`	El cuerpo de la petición supera el máximo.
415	`tipo_no_admitido`	Tipo de contenido no admitido.
500	`error_interno`	Fallo nuestro. Reintenta con espera creciente.
503	`servidor_sin_configurar`	El servidor no está configurado.

Estado del servicio

Qué no se publica todavía

No hay una página de estado en tiempo real de la API: el servicio no está abierto. El estado general de los servicios de la web está en la página de estado. Esta página describe lo que el servidor hace, y una prueba automática la mantiene alineada con el código.