Trash inbox
When a message exhausts its retries, the platform routes it to the Trash: a per-topology inbox of failed messages. Trash entries hold the original payload, the error, and the node where the failure happened. From the Admin UI, an operator can inspect, edit, approve, or reject them — without touching code.
For how a message ends up in Trash (which exception to throw, how OnRepeatException and STOP_AND_FAILED map to retries vs. failures), see Building nodes: Error handling and retries.
What an operator can do #
From a Trash entry in the Admin UI:
- Inspect the payload, the error, and the failing node to understand what happened.
- Edit the payload if the failure was caused by bad data, then Approve to re-inject it from the failed node.
- Approve as-is, after the upstream issue is fixed.
- Bulk-approve a group when many messages failed for the same reason (downstream API was down and is now back).
- Reject if the message is no longer relevant.
The UI actions on a Trash entry are Approve / Edit / Reject (individually or in bulk). Under the hood, Approve performs a replay — the message is re-injected at the failed step, not at the start of the topology, so upstream side effects don't repeat. The word replay refers to that re-injection mechanic; the operator-facing button is Approve.
Operational handoff #
Trash is the channel between developers and operators:
- Developers decide what should retry vs. fail (in code).
- Operators decide what to do with the things that ultimately failed (in the Admin UI).
Wire alerts so the team knows to look at Trash without polling it — see Notifications.
Why Trash beats writing your own dead-letter queue
Every team that has rolled their own dead-letter store eventually rebuilds the same UI: a list, a filter by topology and date, an "edit and resubmit" form, a bulk action. Trash is exactly that, included, and tied to the original process and its logs. Don't build your own.
See also #
- Building nodes: Error handling and retries — the in-code side of the same workflow.
- Operations: Notifications — alert on failed messages.
- Operations: Logging
- Operations: Integration monitoring