Consumption Retry

Retry Triggers

• Consumption failure, including returning a failure status or throwing an unexpected exception.

• Message processing timeout, including queue timeout in PushConsumer.

Main Retry Behaviors

• Retry state machine: Controls message states and transitions during retry.

• Retry interval: The time between a consumption failure (or timeout) and when the message becomes available for re-consumption.

• Maximum retry count: The maximum number of times a message can be retried.

Message retry policy differences

For detailed retry policies, see PushConsumer consumption retry policy and SimpleConsumer consumption retry policy.

Retry State Machine

Example: In the diagram above, assume a message stays in Ready for 5 seconds and takes 6 seconds to process.

Each retry cycle follows Ready → Inflight → WaitingRetry. The retry interval is the time between a failure (or timeout) and when the message becomes Ready again. The actual time between two consumption attempts also includes processing time and Ready duration. For example:

• At 0 s, the message enters Ready.

• Due to consumer processing speed, consumption starts at 5 s. After 6 seconds (at 11 s), an exception occurs and the client returns failure.

• Retry cannot start immediately—it must wait for the retry interval.

• At 21 s, the message becomes Ready again.

• The client begins re-consuming 5 seconds later.

Thus, the actual interval between two consumption attempts is: processing time + retry interval + Ready duration = 21 s.

Retry Intervals

• Unordered messages (non-ordered messages): The retry interval uses a stepped time approach, as follows:

  Retry attempt	Retry interval	Retry attempt	Retry interval
  1	10 seconds	9	7 minutes
  2	30 seconds	10	8 minutes
  3	1 minute	11	9 minutes
  4	2 minutes	12	10 minutes
  5	3 minutes	13	20 minutes
  6	4 minutes	14	30 minutes
  7	5 minutes	15	1 hour
  8	6 minutes	16	2 hours

  Note

  If retry attempts exceed 16, all subsequent retries use a 2-hour interval.

• Ordered messages: Use a fixed retry interval. For specific values, see Parameter limits.

Maximum Retry Count

• Default value: 16.

• Maximum: 1,000.

For PushConsumer, the maximum retry count is controlled by consumer group metadata. To modify it, see Modify maximum retry count.

For example, if the maximum retry count is 3, the message is delivered up to 4 times: once originally and three times via retry.

Usage Example

To trigger retry in PushConsumer, simply return a consumption failure status code. Unexpected exceptions are automatically caught by the SDK.

SimpleConsumer simpleConsumer = null;
        // Consumption example: Use PushConsumer to consume normal messages. Return an error on failure to trigger retry.
        MessageListener messageListener = new MessageListener() {
            @Override
            public ConsumeResult consume(MessageView messageView) {
                System.out.println(messageView);
                // Return FAILURE to trigger automatic retry until the maximum retry count is reached.
                return ConsumeResult.FAILURE;
            }
        };
            

View Consumption Retry Logs

For ordered messages, PushConsumer performs retries on the client side. The server cannot access detailed retry logs. If message trace shows delivery failure for an ordered message, check the consumer client logs for maximum retry count and client information.

For the client log path, see Log configuration.

Search for these keywords in client logs to quickly locate consumption failure details:

Message listener raised an exception while consuming messages
Failed to consume fifo message finally, run out of attempt times

Retry State Machine

Unlike PushConsumer, SimpleConsumer uses a pre-allocated retry interval. When fetching a message, the consumer sets an InvisibleDuration parameter—the maximum allowed processing time. On failure, the next retry interval reuses this value without additional configuration.

Because InvisibleDuration is pre-allocated, it may differ significantly from actual processing time. You can modify it via API.

For example, if you initially set processing time to 20 ms but actual processing exceeds this, extend InvisibleDuration to avoid premature retries.

As shown below, the new InvisibleDuration takes effect immediately—restarting the invisibility timer from the API call moment.

Retry Interval

Retry interval = InvisibleDuration − Actual processing time

SimpleConsumer controls retry intervals via InvisibleDuration. For example, if InvisibleDuration is 30 ms and processing fails after 10 ms, the next retry occurs after 20 ms. If processing doesn’t finish within 30 ms and no result is returned, the message times out and retries immediately (0 ms interval).

Maximum Retry Count

• Default value: 16.

• Maximum: 1,000.

For SimpleConsumer, the maximum retry count is controlled by consumer group metadata at creation. To modify it, see Modify maximum retry count.

For example, if the maximum retry count is 3, the message is delivered up to 4 times: once originally and three times via retry.

Usage Example

To trigger retry in SimpleConsumer, simply wait.

 // Consumption example: Use SimpleConsumer to consume normal messages. To trigger retry, remain silent and let the message time out. The server will automatically retry.
        List<MessageView> messageViewList = null;
        try {
            messageViewList = simpleConsumer.receive(10, Duration.ofSeconds(30));
            messageViewList.forEach(messageView -> {
                System.out.println(messageView);
                // On failure, ignore the message. It will become visible again and be retried.
            });
        } catch (ClientException e) {
            // If pull fails due to throttling or other system issues, retry the receive request.
            e.printStackTrace();
        }

gRPC SDK

• Modify via OpenAPI: Update consumer group

• Modify via console:

  To access the setting:

  1. On the Instances page, click the target instance name.

  2. In the navigation pane on the left, click Groups. On the Groups page, click Create Group.

  In the Create Group dialog, set Group ID (1–60 characters), Delivery Order (Concurrent Delivery or Ordered Delivery), and Description. Expand Advanced Settings to configure the retry policy as Exponential Backoff, set Maximum Retry Count (default: 16), and toggle Retain Dead-letter Messages (default: off; if off, messages exceeding retry count are discarded).

Remoting SDK

• Modify via Remoting SDK parameter: Set the maxReconsumeTimes property of the consumer.

Retry Reasonably—Avoid Using Retry for Rate Limiting

As noted in Scenarios, message retry suits rare business failures—not systemic or continuous failures like rate limiting.

• Incorrect example:

  If consumption rate triggers throttling, return failure and wait for retry.

• Correct example:

  If consumption rate triggers throttling, delay message fetching and consume later.

How to Set Message Consumption Timeout?

consumer.setConsumeTimeout(15); // Unit: minutes. Range: 1–180 minutes