Message lifecycle
Possible statuses
| Status | Meaning |
|---|---|
NAO_PROCESSADA | Received and persisted, not queued yet |
ENFILEIRADA | Job created in BullMQ, waiting for a worker |
PROCESSANDO | A worker is delivering it right now |
PROCESSADA | Delivered successfully |
AGUARDANDO_REENVIO | Failed and waiting out the backoff before the next attempt |
ERRO_ENTREGA | Technical failure after exhausting retries (timeout, connection, HTTP 5xx) |
ERRO_NEGOCIO | The destination responded, but the response matched a business error rule |
ERRO_COLETA | Failure while fetching from the external source (step 1 of a Collector) |
CANCELADA | Manually discarded from the cancellation screen |
These values are literal API identifiers, not display labels. They are Portuguese strings in
the contract and are never translated — use them exactly as written when filtering
(GET /mensagens?status=ERRO_ENTREGA) or reading a response body. The interface shows a
translated label for each one, but the stored and transported value does not change with the
language.
ERRO_COLETA and ERRO_ENTREGA mean different things in a Collector: the first is a failure
reading the source; the second, a failure forwarding data that was already read successfully.
Technical error vs. business error
- Technical error — the destination did not answer, timed out or returned a transport error. CMS retries according to the Definition’s retry count and backoff.
- Business error — the destination answered normally (HTTP 200 even), but the response content matches a pattern registered under Business Errors. Retrying will not help: someone must fix the data. Optionally the rule blocks the Interface, holding back further messages until someone intervenes.
Where the attempts happen
The Definition’s Maximum attempts applies to both delivery modes, but in different places:
| Mode | Where it retries | Interval between attempts |
|---|---|---|
| Asynchronous | In the queue job, outside the receiving request | 10 seconds |
| Synchronous | Inside the receiving request itself | 1 second |
The short interval in synchronous mode is deliberate: there, whoever sent the message is waiting for the reply, and every extra round is added latency. It is meant to ride out a momentary failure — a refused connection, the 502 of a proxy restarting — not to wait for a destination to come back from scratch. That is what asynchronous delivery is for.
In either mode, the loop stops before exhausting the attempts when:
- the delivery succeeds;
- the destination returns a business error — retrying would return exactly the same error;
- the destination Application is offline on the keep-alive — not even the first attempt goes out.
Every attempt writes its own processing record: that history is what the message detail shows.
Reprocessing
Messages in ERRO_ENTREGA or ERRO_NEGOCIO can be resent from Delivery Errors
(/messages/delivery-errors), individually or in bulk. Reprocessing creates a new attempt recorded
in the message history — nothing is overwritten.
Retention
The cleanup job (limpeza module, configurable under Schedulers) runs every
night and purges old messages according to the retention days set on each Interface — retention
is per Interface, not global. The Storage report shows accumulated volume by Application →
Interface → Definition, with each one’s retention alongside.