Retry policies and dead-letter queues - ApsaraMQ for RocketMQ

When a message fails to be delivered in a Message Integration task, the system automatically retries delivery. If all retry attempts are exhausted, the message is sent to a dead-letter queue or discarded, depending on the fault tolerance policy. Retry policies and dead-letter queues work together to balance message reliability against delivery throughput.

How it works

When a message delivery fails, the system applies the configured retry policy. The outcome depends on both the retry policy and the fault tolerance policy:

Message delivery fails
        |
        v
  Retry policy applied
  (backoff or exponential decay)
        |
        |-- Retry succeeds --> Message delivered
        |
        +-- All retries exhausted
                |
                v
        Fault tolerance policy
                |
                |-- Allowed
                |       |
                |       |-- Dead-letter queue enabled --> Raw data sent to DLQ
                |       |
                |       +-- Dead-letter queue disabled --> Message discarded
                |
                +-- Prohibited --> Task blocked (status: Ready)

Retry policies

A retry policy controls how many times the system retries a failed message and how long it waits between attempts. Message Integration supports two retry policies.

Backoff retry (default)

The system retries a failed message up to 3 times. Each retry interval is a random value between 10 and 20 seconds.

Use backoff retry when transient failures are likely to resolve quickly and a small number of retries is sufficient.

Exponential decay retry

The system retries a failed message up to 176 times over a maximum period of 1 day. The retry interval doubles after each attempt, starting at 1 second and capping at 512 seconds:

Attempt	Retry interval
1	1 second
2	2 seconds
3	4 seconds
4	8 seconds
5	16 seconds
6	32 seconds
7	64 seconds
8	128 seconds
9	256 seconds
10-176	512 seconds

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

Use exponential decay retry when failures may take longer to resolve, such as downstream service outages or temporary resource unavailability.

Choose a retry policy

Scenario	Recommended policy	Reason
Transient network errors or brief service hiccups	Backoff retry (default)	Resolves quickly with minimal retries
Downstream service outages or extended unavailability	Exponential decay retry	Provides sustained retries over a longer period without overwhelming the target

Fault tolerance policies

A fault tolerance policy determines what happens after all retry attempts are exhausted. Message Integration supports two fault tolerance policies.

Fault tolerance allowed

If a message still fails after the maximum number of retries, the system delivers the raw data to the dead-letter queue (if enabled) or discards the message. Other messages continue to flow normally.

Fault tolerance prohibited

If a message still fails after the maximum number of retries, message processing is blocked. The task status changes to Ready.

Note

If retries cannot be performed due to invalid resource configurations, the task status changes to Startup Failed instead of Ready.

Choose a fault tolerance policy

Scenario	Policy	Behavior after retries exhausted
Partial message loss is acceptable, and remaining messages must keep flowing	Fault tolerance allowed	Failed message goes to DLQ or is discarded; other messages continue
Every message must be delivered, even if it means blocking until the issue is resolved	Fault tolerance prohibited	Task is blocked until the issue is resolved

Dead-letter queues

A dead-letter queue (DLQ) takes effect in a task. If a message fails to be delivered after all retry attempts are exhausted, the system sends the raw data to the dead-letter queue.

Dead-letter queues are disabled by default. To preserve undeliverable messages, enable a dead-letter queue in the task configuration.

Supported queue types

The following services can serve as dead-letter queues:

ApsaraMQ for RocketMQ
Simple Message Queue (formerly MNS)
ApsaraMQ for Kafka
Event buses in EventBridge

Configuration summary

Setting	Options	Default
Retry policy	Backoff retry, Exponential decay retry	Backoff retry
Fault tolerance policy	Allowed, Prohibited	-
Dead-letter queue	Enabled, Disabled	Disabled