Dead-letter queues and replay

Your dead-letter queue Available now

Every consumer connection has its own dead-letter queue. A message your consumer receives and doesn't acknowledge (or delete) comes back when its visibility runs out: 60 seconds by default. After the connection's attempts before the dead-letter queue (5 unless you chose otherwise when you created it) it moves to the dead-letter queue, and the rest of its story flows again.

• Consumer connections in the portal shows how many messages are in each dead-letter queue.
• The pull API reads the main queue only. A verified reader role can read the dead-letter queue like the main one: inspect a message, or delete it once dealt with.
• Messages wait there for 14 days.
• Alert on it. A message in your dead-letter queue is a story your product stopped following. The bus emails your workspace when a dead-letter queue grows (see Notifications), and RND is alerted too.

Redrive Available now

Once you've fixed your handler, move the messages from your dead-letter queue back to your queue. In the portal, open Consumer connections, then Redrive DLQ on the connection:

• All messages: the whole dead-letter queue is moved in the background. The connection shows the redrive as running, then how many messages it moved.
• Only some: up to 100 of the oldest messages are moved there and then, so you can try a few first.

A redrive delivers at least once. When you move only some, a message sent to your queue that then can't be removed from the dead-letter queue stays there too. A redrive within 5 minutes sends it with the same deduplication id, so SQS delivers it once; a later redrive can deliver it a second time. De-duplicate on message_id, as for any message.

Redriven messages arrive behind newer messages of the same story, so your consumer must keep the highest sequence_number per story and drop older snapshots. See Order, duplicates and snapshots.

Replay Available now

The bus archives every accepted message: 30 days on the Sandbox, 7 days on Preview. You can have a time range from the archive delivered to your connection's queue again. Use it to rebuild your consumer's state after an outage ("the CMS was down for an hour"), or to test that it's idempotent.

In the portal, open Consumer connections, then Replay on the connection. Choose where to start (at most the archive's retention ago) and, if you like, where to stop; without an end it replays up to now.

• Only that connection receives the replay, through its own message types and topic prefix. Every other queue on the bus, yours included, sees nothing.
• In order per story. Each story's messages arrive in the order the bus accepted them.
• Everything replayed is a message you may already have: de-duplicate on message_id, and keep the highest sequence_number per story. The consumer tests check both.
• Replay only covers messages accepted since your workspace's topic was made.

Who can, and how often

• Developers, admins and owners of the workspace, for their own organisation's connections. When another organisation's app is connected in your workspace (a vendor's app in a publisher's house), you can't replay into it or redrive it: that organisation does, from its own workspace (see Your connections in a house), so ask them.
• One at a time per connection: one replay and one redrive may run at once; start another when it has finished.
• Per connection per day (UTC): 3 replays and 10 redrives. A start the bus refused doesn't count. If you need more, ask RND.
• A revoked connection can't be replayed into or redriven: restore it first.

Your connections in a house

A vendor replays into, and redrives, its own consumer connections in a publisher's house itself, from its own vendor workspace: open Houses, then Replay or Redrive DLQ on the connection. It works as above, with the same roles (developers, admins and owners of your vendor workspace) and the same limits per connection. It shows there when it has finished; the Replay and redrive email covers your own workspace's connections only, not your connections in a house.

The publisher sees on its Consumer connections page that a replay or redrive happened: when, the time range or how many messages, and how it ended. Each start and finish is recorded in its audit log, naming your organisation, never your people. It sees no message it couldn't already see: a replay delivers only into your connection's queue. Each start is also recorded in your own workspace's audit log, with who started it.

When it finishes

The connection shows the latest replay and redrive: running, finished, failed or cancelled, with when it ran and how many messages a redrive moved. A replay whose status the bus still can't read after 24 hours is shown as failed, status unknown: some or all of its range may have been delivered, so check your queue before you replay it again. Your workspace gets a Replay and redrive email when one finishes; developers and up get it unless your admins choose otherwise (see Notifications). Every start and every finish is recorded in the workspace's audit log.