> ## Documentation Index
> Fetch the complete documentation index at: https://docs.basaltic.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# FIFO and dead-letter queues

> Control ordering, deduplicate sends, and isolate messages that repeatedly fail processing.

FIFO ordering and dead-letter handling solve different problems. FIFO controls
which message a group can receive next. Redrive moves repeatedly abandoned
messages out of the source queue so they can be investigated separately.

## FIFO groups

A queue is FIFO when its name ends in `.fifo`. Every send requires a
`message_group_id`, up to 128 bytes. Use a group for one ordered stream, such
as a customer or order. Different groups can progress independently.

An earlier unexpired message in a group blocks later messages while it is
leased or delayed. A long-running or repeatedly failing message can therefore
hold up its whole group. Acknowledging it, its expiry, or moving it to a
dead-letter queue lets the group progress.

## Deduplication

FIFO sends need a `message_deduplication_id`, up to 128 bytes, unless the queue
has content-based deduplication enabled. Reusing the same deduplication ID in
the queue within five minutes returns the existing message ID without adding
another message. The send result marks it as a duplicate.

With content-based deduplication, an omitted ID is derived from the body.
Attributes are not part of that hash. Supply explicit IDs when identical
bodies represent different business events. Deduplication applies to sends
within the window; a consumer can still receive a message again after a lease
expires.

A FIFO send body might contain:

```json theme={null}
{
  "body": "{\"order_id\":\"A-1001\",\"status\":\"paid\"}",
  "message_group_id": "customer-42",
  "message_deduplication_id": "order-A-1001-paid"
}
```

## Dead-letter queues

Create the target before attaching it. It must be in the same account and
region, have the same type as the source, and differ from the source queue.
Choose retention long enough for your investigation process.

Set both redrive fields on the source queue:

```json theme={null}
{
  "redrive_policy": {
    "dead_letter_queue": "failed-orders.fifo",
    "max_receive_count": 5
  }
}
```

The target accepts a queue name, UUID, or CRN in requests and is returned as a
resource reference. The receive count measures leases, not application
exceptions. After the maximum number of receives and expiry of the active
lease, redrive can move the message. This is asynchronous; it need not appear
in the target immediately when the last lease expires. The target starts a new
retention window measured from the move, with a reset receive count and no
active lease.

A poison message blocks its FIFO group until it is removed, expires, or moves
to the dead-letter queue. Redrive allows later messages to proceed, so decide
whether skipping the failed business event is acceptable for that stream.

## Investigate and recover

Consume or peek at the dead-letter queue, fix the consumer or offending data,
and deliberately republish messages you want to process again. A new send is
a new queue message; preserve your own business event ID for idempotency.
Do not republish every failure automatically into a loop.

Detach a policy with `redrive_policy: null` on the source queue's PATCH request.
Detaching a target does not move its existing messages back to the source.
The console shows queues that refer to a dead-letter target so their bindings
can be removed before deletion.

A Notifications subscription can also use a queue for failed delivery envelopes.
That policy handles the notification service's attempt to reach an endpoint;
this queue policy handles a consumer's failure to acknowledge a leased message.
See [notification failures](/notifications/delivery#dead-letter-queues).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.