Skip to Content
Changelog23/10/2026 · Authority errors: 424 and 503 instead of 502 and 504

Authority errors: 424 and 503 instead of 502 and 504

23/10/2026

Behaviour change. The HTTP codes the API uses to report a failure of an authority (TGSS/RED System, SEPE, DEHU, AEAT, Navarre Tax Office) or of a connected system change. From Monday 26/10/2026 the API never returns 502 or 504 on purpose. The body does not change: it is still {success: false, message, status, data, errors}, with the reason in message.

Why

We have added a new perimeter protection layer to the API (malicious traffic filtering / WAF and protection against denial-of-service attacks). This layer treats 502 and 504 as network failures and replaces their content with a generic message, so the reason for the error did not reach the client: our JSON was lost and, with it, the message holding the reason for the TGSS or SEPE rejection. 424 and 503 arrive intact.

What changes

SituationBeforeNow
The authority answered and rejected the request (or rejected our certificate)502424 Failed Dependency. Where applicable, message starts with SISTEMA RED: , SEPE: or DEHU: and the response carries the X-Saltra-Error: organism-rejected header. No Retry-After.
We could not communicate with the authority (connection, timeout on a query, invalid response, down)502 / 504503 with retryable: true and retry_after in the body, and the Retry-After (60 seconds by default) and X-Saltra-Error: organism-unavailable headers.
Unknown outcome of a write (registration, deregistration, contract change, communication to SEPE that timed out or was not confirmed)504 / 502503 without Retry-After and without retryable; timeout: true when time ran out. The message asks you to check whether it was registered before retrying.
Authority maintenance503 + maintenance: true + Retry-AfterNo change.
Saltra rejects the data (validation)422No change.

retryable is a new field, at the root of the body next to maintenance and timeout.

What you should do

  • Read the body on every status code, not only on 200: the reason is in message.
  • 424: do not retry without fixing the data (or changing the certificate, if that is what the authority rejected). Repeating the same request returns the same rejection.
  • 503 with Retry-After: retry after the seconds given by the header (or retry_after). Do not poll at a fixed interval.
  • 503 without Retry-After: do not retry blindly. First check whether the request was registered (look up the movement, the TA or the relevant mailbox); resending it could duplicate it.
  • A 502, 504 or 52x you may still receive is generated by the network infrastructure, not by the API, and does not carry our body. Treat it as a connection failure: if it was a write, check whether it was registered before retrying.

If your integration checked status == 502 to detect an authority rejection, or 504 for a timeout, you need to adapt it: a rejection is now 424 and a timeout is 503. If you treated any 5xx as “retry”, stop retrying the 503 without Retry-After.

The status code tables of each authority have been updated: Social Security, SEPE, DEHU, AEAT and Navarre Tax Office.

Last updated on