Errores de organismo: 424 y 503 en lugar de 502 y 504

23/10/2026

Cambio de comportamiento. Cambian los códigos HTTP con los que la API informa de un fallo de un organismo (TGSS/Sistema RED, SEPE, DEHU, AEAT, Hacienda de Navarra) o de un sistema conectado. A partir del lunes 26/10/2026 la API no devuelve nunca a propósito 502 ni 504. El cuerpo no cambia: sigue siendo {success: false, message, status, data, errors}, con el motivo en message.

Por qué

Hemos incorporado una nueva capa de protección perimetral de la API (filtrado de tráfico malicioso / WAF y protección frente a ataques de denegación de servicio). Esta capa trata los 502 y 504 como fallos de red y sustituye su contenido por un mensaje genérico, por lo que el motivo del error no llegaba al cliente: se perdía nuestro JSON y, con él, el message con el motivo del rechazo de la TGSS o del SEPE. Los códigos 424 y 503 llegan intactos.

Qué cambia

Situación	Antes	Ahora
El organismo ha respondido y ha rechazado el trámite (o ha rechazado nuestro certificado)	`502`	`424 Failed Dependency`. Cuando aplica, `message` empieza por `SISTEMA RED:` , `SEPE:` o `DEHU:` y la respuesta lleva la cabecera `X-Saltra-Error: organism-rejected`. Sin `Retry-After`.
No hemos podido comunicarnos con el organismo (conexión, tiempo agotado en una consulta, respuesta no válida, caído)	`502` / `504`	`503` con `retryable: true` y `retry_after` en el cuerpo, y las cabeceras `Retry-After` (60 segundos por defecto) y `X-Saltra-Error: organism-unavailable`.
Resultado desconocido de una escritura (alta, baja, cambio de contrato, comunicación al SEPE que agotó el tiempo o no confirmó)	`504` / `502`	`503` sin `Retry-After` y sin `retryable`; `timeout: true` cuando se ha agotado el tiempo. El mensaje pide comprobar si se registró antes de reintentar.
Mantenimiento del organismo	`503` + `maintenance: true` + `Retry-After`	Sin cambios.
Saltra rechaza los datos (validación)	`422`	Sin cambios.

retryable es un campo nuevo, en la raíz del cuerpo junto a maintenance y timeout.

Qué debes hacer

Lee el cuerpo en cualquier código, no solo en el 200: el motivo está en message.
424: no reintentes sin corregir los datos (o cambiar el certificado, si es lo que ha rechazado el organismo). Repetir la misma petición devuelve el mismo rechazo.
503 con Retry-After: reintenta después de los segundos que indique la cabecera (o retry_after). No hagas polling a intervalo fijo.
503 sin Retry-After: no reintentes a ciegas. Comprueba antes si el trámite se registró (consulta el movimiento, el TA o el buzón correspondiente); reenviarlo podría duplicarlo.
Un 502, 504 o 52x que aún recibas lo genera la infraestructura de red, no la API, y no trae nuestro cuerpo. Trátalo como un fallo de conexión: si era una escritura, comprueba si se registró antes de reintentar.

Si tu integración comprobaba status == 502 para detectar un rechazo del organismo, o 504 para un tiempo agotado, tienes que adaptarla: el rechazo es ahora 424 y el tiempo agotado es 503. Si tratabas cualquier 5xx como «reintentar», deja de reintentar el 503 sin Retry-After.

Las tablas de códigos de cada organismo están actualizadas: Seguridad Social, SEPE, DEHU, AEAT y Hacienda de Navarra.