Retry policies and dead-letter queues - ApsaraMQ for RocketMQ

When a message fails to be sent through Message Integration, a retry policy determines how and when the system reattempts delivery. If all retries are exhausted, a fault tolerance policy controls whether processing continues or stops. Messages that cannot be delivered after all retries can be routed to a dead-letter queue for inspection.

Message delivery lifecycle

The following diagram shows how retry policies, fault tolerance policies, and dead-letter queues work together when a message fails:

Message send fails
       |
       v
+---------------+     Retries remaining?
| Retry policy  |-------- Yes -----> Wait for interval, then retry
+---------------+
       | No
       v
+-------------------+
| Fault tolerance   |
| policy            |
+-------------------+
       |                          |
   Allowed                   Prohibited
       |                          |
       v                          v
  DLQ enabled?              Block processing;
   |         |              task status -> Ready
  Yes        No
   |         |
   v         v
 Send to    Discard
 dead-letter message
 queue

Retry policies

Message Integration supports two retry policies. Backoff retry is the default.

Policy	Max retries	Interval	Behavior
Backoff retry (default)	3	Random, 10--20 seconds	Retries at random intervals within the range
Exponential decay retry	176	1 s--512 s, doubles each attempt	Total retry window: 1 day

Backoff retry

A failed message is retried up to 3 times. Each retry waits a random interval between 10 and 20 seconds.

Exponential decay retry

A failed message is retried up to 176 times over the course of one day. The interval between consecutive retries doubles with each attempt, up to a maximum of 512 seconds:

Retry	Interval	Retry	Interval
1	1 s	6	32 s
2	2 s	7	64 s
3	4 s	8	128 s
4	8 s	9	256 s
5	16 s	10--176	512 s

After the interval reaches 512 seconds, it remains at 512 seconds for the remaining 167 retries.

Fault tolerance policies

A fault tolerance policy controls what happens after all retries are exhausted. Message Integration supports two modes:

Policy	Behavior after retries exhausted
Fault tolerance allowed	Processing continues. The failed message is sent to the dead-letter queue (if enabled) or discarded.
Fault tolerance prohibited	Processing is blocked. The task status changes to Ready.

Note

If retries cannot start due to errors such as invalid resource configurations, the task status changes to Startup Failed instead of Ready.

Dead-letter queues

A dead-letter queue captures messages that cannot be delivered after all retries are exhausted. When enabled, Message Integration sends the raw data of the failed message to the dead-letter queue. The dead-letter queue feature is disabled by default. Enable it at the task level.

Supported destinations

The following services can serve as dead-letter queues:

Service	Resource type
ApsaraMQ for RocketMQ	Queue
Simple Message Queue (formerly MNS)	Queue
ApsaraMQ for Kafka	Queue
EventBridge	Event bus