Dead letter queues should keep the reason

Dead letter queues are often treated like operational storage.

The message failed too many times. Move it aside. Keep the payload. Investigate later.

That is better than dropping the event, but it still leaves a gap. The queue preserved what failed to move. It did not always preserve why the system gave up.

That missing reason becomes expensive the moment somebody has to decide what happens next.

An operator opens the dead letter queue and sees a payload plus a timestamp. Was the receiver returning 429 for an hour? Did the request keep timing out with no receipt? Did the payload become invalid after a schema change? Did a credential expire? Did the delivery engine hit a local serialization bug before the request left the sender at all?

Those are different failures. A queue that stores only the payload asks the next person to reconstruct the reason from scattered logs and partial memory.

A dead letter entry is a handoff record #

The useful way to think about a dead letter queue is not storage, but handoff.

The delivery engine is handing an unresolved event to a human, another workflow, or a later recovery process. That handoff should include more than the body that did not reach its destination.

At minimum, preserve the original request or event ID, destination, payload identity, last known response class, attempt count, first failure time, most recent failure time, and the rule that moved the event into the dead letter queue. If the last observed state was timeout, keep the uncertainty honest. If the receiver returned a durable rejection, keep that too.

Without that information, the operator is forced to answer the most important question from secondary evidence: what kind of failure is this?

Payload alone encourages the wrong recovery #

When all the team can see is the payload, recovery starts to look the same for every event.

Replay it.

That is sometimes right. It is often lazy. A delivery blocked by a temporary receiver outage may deserve replay. A delivery rejected because the receiver no longer accepts that schema probably needs a code or contract fix first. A delivery that timed out after the receiver may already have committed the side effect needs much more care.

Reason changes recovery. A dead letter queue that keeps reason beside payload makes that visible before another action repeats the original mistake.

Keep the queue transition explainable #

A message does not land in the dead letter queue by magic. Some policy moved it there.

Maybe the system exhausted a retry budget. Maybe the response class was marked non-retryable. Maybe a circuit breaker opened. Maybe validation failed before the first outbound attempt. Maybe an operator intervened. Each path says something different about what the queue entry means.

The dead letter record should keep that transition reason in plain terms. Exhausted retry budget after five timeout-class failures. Moved after receiver returned permanent rejection. Moved after local validation error. Moved by operator replay tool after second failure.

That wording is not decoration. It helps the next person tell the difference between a transport problem, a contract problem, a sender bug, and a deliberate hold.

The queue should preserve the last useful evidence #

Teams often assume logs will fill in the rest. Sometimes they do. Sometimes the retention window is short, the trace ID is missing, or the engineer who knows the logging path is asleep.

A dead letter queue earns more trust when it stores the last useful evidence with the entry itself. That does not mean dumping every log line into the queue. It means preserving the compact evidence the next decision needs: the last response status, the last error class, the last acknowledgment if one exists, and the rule that stopped retries.

This is the same principle behind a good incident handoff. Do not make the next person rediscover the basic facts before they can decide whether to replay, inspect the receiver, patch the contract, or escalate to support.

Replay should depend on the preserved reason #

A mature replay tool can use the dead letter reason as a first filter.

If the entry was dead-lettered after repeated 503 responses and the receiver is healthy again, replay may be appropriate.

If the entry was dead-lettered because the receiver rejected the payload as malformed, replaying the same message without another change should feel suspicious.

If the entry timed out and the system never received a receipt, the recovery path should ask a narrower question first: do we have evidence that the receiver already acted?

The reason does not decide the action automatically. It makes the action reviewable. That is a much better use of a queue than simply collecting messages the system could not deliver.

A dead letter queue is part of product trust #

Customers do not usually ask whether you have a dead letter queue. They notice when support cannot explain what happened to an event, when duplicates appear after a blind replay, or when a failed delivery sits unresolved because the queue record is too thin to route confidently.

That is why dead letter design belongs in the product, not only in the infrastructure layer. Reliable dispatch is not just about moving messages fast. It is about leaving behind enough operating truth that the next person can recover safely.

Stack Dispatch works best when it keeps the payload and the reason together. The payload tells you what the system tried to send. The reason tells you how the system failed to complete the handoff. You need both if the next action is going to be better than guesswork.