Retry-After header on SEPE and TGSS 503 responses

04/10/2026

When SEPE (Contrat@, Certific@) or TGSS/RED System is under maintenance or not operational, the API responds 503 with maintenance: true. Until today that response did not say how long to wait, so the only option was to retry blindly. From today it carries a Retry-After header with the seconds to wait before trying again, just like 429:

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

Respuesta 503

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

The body may also include retry_after (integer, seconds) next to maintenance: true, with the same value as the header. If it is missing, use the header.

The value depends on the case. When Saltra already knows the authority is down (Certific@ under maintenance, for example), it answers without asking it 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.

The body format does not change (success, message, status, errors, maintenance).

What to check in your integration:

Wait for what Retry-After says. Retrying early does not unblock anything: it returns the same 503.
Do not poll at a fixed interval (every 10 seconds, for example) while the authority is down. Schedule the next attempt from the header value.
Status codes and their details are in SEPE errors and Social Security errors.