Documentación

Conecta tus aplicaciones con funciones de la Seguridad Social, SEPE y DEHU.

Parámetros en la cabecera HTTP

Authorization (caracteres): Autorización de la API. Ejemplo: Bearer {token}
X-Cert-Secret (caracteres): Clave secreta asociada al certificado del cliente.

Límites de consultas

Las peticiones autenticadas están limitadas a 80 por minuto en las consultas (GET) y 120 por minuto en las escrituras (POST). El límite se cuenta por certificado (si se envía X-Cert-Secret) o, en su defecto, por usuario autenticado, y por ruta. Las peticiones no autenticadas se limitan a 60 por minuto por IP. Los endpoints de integración pesada —GET /employee-situations y GET /ta-info-for-nss de Seguridad Social, y GET /contrata/data del SEPE— comparten un cupo combinado más bajo, de 30 peticiones por minuto por certificado (o usuario): consumir uno reduce el cupo de los otros dos.

Saltra publica el estado de tu cupo en las cabeceras de todas las respuestas, para que puedas regular el ritmo de tus llamadas antes de agotarlo.

Cabecera	Tipo	Cuándo se envía	Qué indica
`X-Ratelimit-Limit`	entero	Siempre	Peticiones permitidas por minuto.
`X-Ratelimit-Remaining`	entero	Siempre	Peticiones que te quedan en la ventana actual.
`X-Ratelimit-Reset`	timestamp UNIX	Siempre	Instante en que la ventana se renueva y `X-Ratelimit-Remaining` vuelve a su máximo.
`Retry-After`	segundos	En `429` y en los `503` de organismo en mantenimiento (`maintenance: true`) o con el que no hemos podido comunicarnos (`retryable: true`). Nunca en un `424` ni en el `503` de resultado desconocido de una escritura.	Segundos que debes esperar antes de reintentar.

Ejemplo de respuesta correcta:

HTTP/1.1 200 OK
X-Ratelimit-Limit: 80
X-Ratelimit-Remaining: 45
X-Ratelimit-Reset: 1786012860

X-Ratelimit-Reset es un instante absoluto, no una cuenta atrás: se mantiene igual en todas las respuestas de la misma ventana y solo avanza cuando el cupo se renueva. Combinado con X-Ratelimit-Remaining es lo que te permite espaciar las peticiones cuando te acercas al límite, en vez de detenerte en seco.

Al superar el límite, la API responde 429 Too Many Requests y añade Retry-After:

HTTP/1.1 429 Too Many Requests
X-Ratelimit-Limit: 80
X-Ratelimit-Remaining: 0
X-Ratelimit-Reset: 1786012860
Retry-After: 37

El cuerpo sigue el formato de error habitual:

{
  "success": false,
  "status": 429,
  "message": "Too Many Requests"
}

⚠️

Espera los segundos que indique Retry-After antes de reintentar. Reintentar antes de tiempo no adelanta el desbloqueo: consume más cupo y alarga la espera.

Retry-After no es solo del 429: también llega en los 503 en los que el organismo (SEPE, TGSS/Sistema RED, DEHU, AEAT, Hacienda de Navarra) está en mantenimiento (maintenance: true) o no hemos podido comunicarnos con él (retryable: true). En todos los casos respeta ese valor y no hagas polling a intervalo fijo (por ejemplo, cada 10 segundos): reintentar antes de tiempo no desbloquea nada y devuelve la misma respuesta.

Nunca llega en un 424 (el organismo ha rechazado el trámite: no reintentes sin corregir los datos) ni en el 503 sin retryable de una escritura de resultado desconocido (comprueba si se registró antes de reintentar). La API no devuelve nunca a propósito 502 ni 504: lee el cuerpo en cualquier código. Detalle en Seguridad Social › Códigos de estado.