Consuming Dead Letter Messages

Function

This API is used to consume the dead letter messages generated by a specified consumer group. Multiple messages can be consumed at a time. The load of messages consumed each time cannot exceed 512 KB.

Only NORMAL and FIFO queues can consume dead letter messages and therefore can have the Dead Letter Message function enabled.

URI

GET /v1.0/{project_id}/queues/{queue_id}/groups/{consumer_group_id}/deadletters?max_msgs={max_msgs}&time_wait={time_wait}&ack_wait={ack_wait}

Table 1 describes the parameters of this API.

**Table 1** Parameters
Parameter	Type	Mandatory	Description	Value Range
project_id	String	Yes	Indicates the ID of a project.	N/A
queue_id	String	Yes	Indicates the queue ID.	N/A
consumer_group_id	String	Yes	Indicates the consumer group ID. You can obtain the consumer group ID from the response message returned after you call the API to view all consumer groups of a specified queue. For details, see Viewing All Consumer Groups of a Specified Queue.	N/A
max_msgs	Integer	No	Indicates the number of consumable dead letter messages that can be obtained a time. NOTE: The number of dead letter messages actually consumed at a time may be less than the message quantity specified in the consumption request. However, all dead letter messages in the queue will be eventually obtained by the consumer after multiple rounds of consumption.	Value range: 1–10. Default Value: 10.
time_wait	Integer	No	Indicates the waiting time for reading messages when the number of dead letter messages that can be consumed by a consumer group is 0. If a dead letter message is available during the wait period, the message consumption result is returned immediately. If no dead letter message is available until the wait period expires, an empty response will be returned after the wait period ends.	Value range: 1 to 60 seconds. Default value: 3s. The default wait period is 3 seconds even if the API request does not carry the time_wait parameter or the time_wait parameter in the API request is left unspecified.
ack_wait	Integer	No	Indicates the commit submission timeout interval. Acknowledgement within the time specified by this parameter is valid. Otherwise, the system displays a message indicating that the message acknowledgement times out or the handler is invalid.	Value range: 15 to 300 seconds. Default value: 30s. If this parameter is left unspecified or empty, the default value 30s is used.

Example

v1.0/b78a90ae2a134b4b8b2ba30acab4e23a/queues/075ae7da-6ce5-4966-940c-17c19fb5175e/groups/g-5ec247fd-d4a2-4d4f-9876-e4ff3280c461/deadletters?max_msgs=10&ack_wait=30

Request

Request parameters

None.

Example request

None.

Response

Response parameters

Table 2 and Table 3 describe the response parameters.

**Table 2** Response parameters
Parameter	Type	Description
message	JSON object	Indicates the message content.
handler	String	Indicates the message handler.

**Table 3** message parameter description
Parameter	Type	Description
body	JSON	Indicates the message body.
attributes	JSON object	Indicates the list of attributes.

Example response

[{
  "message" : {
   "body" : {
    "foo" : "123="
   },
   "attributes": {
       "attribute1": "value1",
       "attribute2": "value2"
        }
  },
  "handler" : "eyJjZyI6Im15X2pzb25fZ3JvdXAiLCJjaSI6InJlc3QtY29uc3VtZXItYzNlNThiNjEtYzA0NC00NGJkLTkxM2ItZDgzNjljNmJhYTQxIiwiY291bnQiOjAsIm9mZnNldCI6MCwicCI6MCwidCI6InRlc3QyIn0="
 }, {
  "message" : {
   "body" : {
    "foo" : "123="
   },
   "attributes": {
       "attribute1": "value1",
       "attribute2": "value2"
        }
  },
  "handler" : "eyJjZyI6Im15X2pzb25fZ3JvdXAiLCJjaSI6InJlc3QtY29uc3VtZXItYzNlNThiNjEtYzA0NC00NGJkLTkxM2ItZDgzNjljNmJhYTQxIiwiY291bnQiOjAsIm9mZnNldCI6MSwicCI6MCwidCI6InRlc3QyIn0="
 }
]

Status Code

Table 4 lists the status code indicating that the operation is successful. For details about the status codes indicating that the operation fails, see Status Code.