Cabecera Retry-After en los 503 de SEPE y TGSS

04/10/2026

Cuando el SEPE (Contrat@, Certific@) o la TGSS/Sistema RED están en mantenimiento o no operativos, la API responde 503 con maintenance: true. Hasta hoy esa respuesta no decía cuánto esperar, así que la única opción era reintentar a ciegas. A partir de hoy lleva la cabecera Retry-After con los segundos que debes esperar antes de volver a intentarlo, igual que el 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
}

El cuerpo puede traer además retry_after (entero, segundos) junto a maintenance: true, con el mismo valor que la cabecera. Si no viene, usa la cabecera.

El valor depende del caso. Cuando Saltra ya sabe que el organismo está parado (por ejemplo, Certific@ en mantenimiento), responde sin volver a consultarlo y Retry-After son los segundos que faltan para que lo compruebe de nuevo (hasta 300 segundos, 5 minutos). En el resto de paradas es un valor por defecto de unos minutos.

El formato del cuerpo no cambia (success, message, status, errors, maintenance).

Qué revisar en tu integración:

Espera lo que indique Retry-After. Reintentar antes no desbloquea nada: devuelve el mismo 503.
No hagas polling a intervalo fijo (por ejemplo, cada 10 segundos) mientras el organismo está parado. Programa el siguiente intento con el valor de la cabecera.
Los códigos de estado y su detalle están en Errores del SEPE y Errores de la Seguridad Social.