SEPE

Connect your applications to SEPE services.

HTTP header parameters

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

Base URL

https://api.saltra.es/api/v4/sepe

Errors

Errors returned by the SEPE API, or validation errors.

• success (boolean) : Returns “true” when everything is correct, and “false” when there are errors.
• message (string) : The response message.
• errors (array) : Errors captured by the API, either from SEPE or validation errors.
  • sepe: Errors related to SEPE.
  • regimen: Validation errors.
• maintenance (boolean) : Set when SEPE is under maintenance.
• retry_after optional (integer) : On 503 with maintenance: true or with retryable: true: the same seconds as the Retry-After header. If it is missing, use the header.
• retryable optional (boolean) : true on 503 responses where we could not communicate with the authority; retry after Retry-After. It is absent on 424 and on the unknown-outcome 503 of a write.

Response

{
  "success": false,
  "message": "Página no operativa, inténtelo de nuevo más tarde. StatusCode: 500",
  "status": 500,
  "data": [],
  "errors": {
    "sepe": [
      "Página no operativa, inténtelo de nuevo más tarde. StatusCode: 500"
    ],
    "regimen": ["El campo regimen es obligatorio."]
  },
  "maintenance": true
}

Status codes

The HTTP status tells you whether the query has an answer, whether the problem is in what you sent us, or whether the failure is on the SEPE side. Use it to decide whether retrying is worthwhile.

Example 503 (Certific@ under maintenance):

HTTP/1.1 503 Service Unavailable
Content-Type: application/json
Retry-After: 120

{
  "success": false,
  "message": "SEPE: SEPE en mantenimiento.",
  "status": 503,
  "errors": {
    "sepe": ["SEPE: SEPE en mantenimiento."]
  },
  "maintenance": true,
  "retry_after": 120
}

The Retry-After value depends on the case. When Saltra already knows SEPE is down (Certific@ under maintenance, for example), it answers without asking SEPE again, and Retry-After is the number of seconds until it checks again (up to 300 seconds, 5 minutes). For any other outage it is a default value of a few minutes. On the 503 with retryable: true (we could not communicate with SEPE) it is 60 seconds by default.

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.

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"
}