Skip to Content
Documentation

Documentation

Connect your applications to Social Security, SEPE and DEHU services.

HTTP header parameters

  • Authorization (string): API authorisation. Example: Bearer {token}
  • X-Cert-Secret (string): Secret key associated with the client certificate.

Rate limits

Authenticated requests are limited to 80 per minute for reads (GET) and 120 per minute for writes (POST). The limit is counted per certificate (if X-Cert-Secret is sent) or, failing that, per authenticated user, and per route. Unauthenticated requests are limited to 60 per minute per IP. The heavy-integration endpoints —GET /employee-situations and GET /ta-info-for-nss from Social Security, and GET /contrata/data from SEPE— share a lower combined quota of 30 requests per minute per certificate (or user): using one reduces the quota of the other two.

Saltra reports your quota status in the headers of every response, so you can pace your calls before running out.

HeaderTypeWhen it is sentWhat it means
X-Ratelimit-LimitintegerAlwaysRequests allowed per minute.
X-Ratelimit-RemainingintegerAlwaysRequests left in the current window.
X-Ratelimit-ResetUNIX timestampAlwaysMoment the window renews and X-Ratelimit-Remaining returns to its maximum.
Retry-AftersecondsOn 429 and on 503 when the authority is under maintenance (maintenance: true) or we could not communicate with it (retryable: true). Never on a 424 or on the unknown-outcome 503 of a write.Seconds to wait before retrying.

Example of a successful response:

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

X-Ratelimit-Reset is an absolute instant, not a countdown: it stays the same across every response in the same window and only moves forward when the quota renews. Combined with X-Ratelimit-Remaining, it is what lets you space out requests as you approach the limit instead of stopping dead.

Once the limit is exceeded, the API responds 429 Too Many Requests and adds Retry-After:

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

The body follows the usual error format:

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

Wait the number of seconds given by Retry-After before retrying. Retrying early does not unblock you sooner: it consumes more quota and lengthens the wait.

Retry-After is not only for 429: it also comes with every 503 where the authority (SEPE, TGSS/RED System, DEHU, AEAT, Navarre Tax Office) is under maintenance (maintenance: true) or we could not communicate with it (retryable: true). In every case honour that value and do not poll at a fixed interval (every 10 seconds, for example): retrying early does not unblock anything and returns the same response.

It never comes with a 424 (the authority rejected the request: do not retry without fixing the data) or with the 503 without retryable of a write with an unknown outcome (check whether it was registered before retrying). The API never returns 502 or 504 on purpose: read the body on every status code. Details in Social Security › Status codes.

Last updated on