Sends a dead-letter message to a consumer group for consumption based on a specified message ID.
Usage notes
After the number of retries to send a message to a consumer group for consumption reaches the upper limit and the message is not consumed by a consumer in the group, the message is added to the dead-letter queue of the consumer group. The message is a dead-letter message. After you resend the dead-letter message to the consumer group for consumption and the message fails to be consumed again after the maximum number of retries, a dead-letter message with the same message ID is added to the dead-letter queue. You can view the details of the dead-letter message on the Dead-letter Queues page in the Message Queue for Apache RocketMQ console or by calling the API operations that are used to query dead-letter messages. You can obtain the number of consumption failures for a message based on the number of dead-letter messages with the same message ID in the dead-letter queue.
- A dead-letter message is a message that fails to be consumed after the number of consumption retries reaches the upper limit. Generally, dead-letter messages are caused by an incorrect consumption logic. We recommend that you troubleshoot the consumption failures and then call this operation to send the message to the consumer group for consumption again.
- Message Queue for Apache RocketMQ does not manage the status of dead-letter messages based on the consumption status of the dead-letter messages. After you call this operation to send a dead-letter message to a consumer group and the message is consumed, Message Queue for Apache RocketMQ does not automatically remove the dead-letter message from the dead-letter queue. You must manage dead-letter messages and determine whether to send a dead-letter message to a consumer group for consumption. You need to remove the dead-letter messages that are consumed. This way, you do not resend and reconsume the messages that are consumed.
Request limit
Each Alibaba Cloud account can call this operation up to 10 times per second. If the number of requests that you send to call this operation within 1 second reaches the request limit, new requests fail. This may interrupt your business. For information about the request limit of each operation, see API rate limits.
Authorization
By default, only Alibaba Cloud accounts can call this operation. A Resource Access Management (RAM) user can call this operation only after the RAM user is granted the required permissions. The following table describes the permissions that must be granted to a RAM user to call this operation. For information about how to grant permissions, Policies and examples.
|
API |
Action |
Resource in an instance that uses a namespace |
Resource in an instance that does not use a namespace |
|---|---|---|---|
|
OnsDLQMessageResendById |
mq:QueryInstanceBaseInfo mq:ResendDLQMessage |
acs:mq:*:*:{instanceId}%{groupId} |
acs:mq:*:*:{groupId} |
Request parameters
| Parameter | Type | Required | Example | Description |
|---|---|---|---|---|
| Action | String | Yes | OnsDLQMessageResendById |
The operation that you want to perform. Set the value to OnsDLQMessageResendById. |
| MsgId | String | Yes | 0BC16699343051CD9F1D798E7734**** |
The ID of the dead-letter message that you want to send to a consumer group for consumption. |
| GroupId | String | Yes | GID_test_group_id |
The ID of the consumer group to which you want to send the dead-letter message. |
| InstanceId | String | Yes | MQ_INST_188077086902****_BXSuW61e |
The ID of the Message Queue for Apache RocketMQ instance that contains the message. |
Response parameters
| Parameter | Type | Example | Description |
|---|---|---|---|
| RequestId | String | D94CC769-4DC3-4690-A868-9D0631B1**** |
The ID of the request. The system generates a unique ID for each request. You can troubleshoot issues based on the request ID. |
| Data | Array of String | 0BC16699343051CD9F1D798E7734**** |
The ID of the message. |
Examples
Sample requests
http(s)://ons.cn-hangzhou.aliyuncs.com/?Action=OnsDLQMessageResendById
&GroupId=GID_test_group_id
&InstanceId=MQ_INST_188077086902****_BXSuW61e
&MsgId=0BC16699343051CD9F1D798E7734****
&<Common request parameters>Sample success responses
XML format
HTTP/1.1 200 OK
Content-Type:application/xml
<OnsDLQMessageResendByIdResponse>
<RequestId>D94CC769-4DC3-4690-A868-9D0631B1****</RequestId>
</OnsDLQMessageResendByIdResponse>JSON format
HTTP/1.1 200 OK
Content-Type:application/json
{
"Data" : [ ],
"RequestId" : "D94CC769-4DC3-4690-A868-9D0631B1****"
}Error codes
For a list of error codes, visit the API Error Center.
Send a dead-letter message to a consumer in the console
You can also send a dead-letter message to a consumer group for consumption in the Message Queue for Apache RocketMQ console. For more information, see Dead-letter queues.