BatchDeleteMessage API for deleting multiple messages from a queue - Simple Message Queue (formerly MNS)

Deletes up to 16 messages from a queue in a single request.

Important

A batch delete request contains multiple subrequests. Some subrequests can fail while others succeed. HTTP status code 204 is returned only when all subrequests succeed. If any subrequest fails, check the error details for each failed entry in the response body.

Name	Value
API	BatchDeleteMessage
Action	mns:BatchDeleteMessage
Resource	acs:mns:$region:$accountid:/queues/$queueName/messages

How it works

To delete messages from a queue, send their receipt handles in a BatchDeleteMessage request. A receipt handle is returned in the response of a ReceiveMessage or BatchReceiveMessage call and uniquely identifies a specific receive event.

The message lifecycle follows these steps:

Receive messages from the queue (ReceiveMessage or BatchReceiveMessage).
Process each message in your application.
Delete processed messages (DeleteMessage or BatchDeleteMessage).

Pair BatchReceiveMessage with BatchDeleteMessage to reduce the number of API calls and improve throughput.

Request syntax

DELETE /queues/$queueName/messages HTTP/1.1

Headers

No operation-specific request headers. For common headers, see Common parameters.

Body

The request body is in XML format. Wrap each receipt handle in a <ReceiptHandle> element inside a <ReceiptHandles> root element.

Schema:

<ReceiptHandles xmlns="http://mns.aliyuncs.com/doc/v1/">
    <ReceiptHandle>string</ReceiptHandle>
    <ReceiptHandle>string</ReceiptHandle>
    <!-- Up to 16 entries -->
</ReceiptHandles>

Element	Type	Required	Description
ReceiptHandles	Container	Yes	Root element that contains one or more `ReceiptHandle` child elements.
ReceiptHandle	String	Yes	A receipt handle returned by ReceiveMessage or BatchReceiveMessage. Each handle identifies a specific receive event for a message.

Response

Success (all messages deleted)

HTTP status code: 204 NoContent

No operation-specific response headers or response body.

Partial failure

When one or more subrequests fail, the response includes an HTTP error status code and an XML body that lists each failed entry.

Schema:

<Errors xmlns="http://mns.aliyuncs.com/doc/v1/">
    <Error>
        <ErrorCode>string</ErrorCode>
        <ErrorMessage>string</ErrorMessage>
        <ReceiptHandle>string</ReceiptHandle>
    </Error>
</Errors>

Element	Type	Description
Errors	Container	Root element that contains one or more `Error` child elements.
Error	Container	Details of a single failed deletion.
ErrorCode	String	Machine-readable error code. See Error codes.
ErrorMessage	String	Human-readable error description.
ReceiptHandle	String	The receipt handle of the message that failed to delete. Match this value against the handles in your request to identify which message was not deleted.

Examples

Request

DELETE /queues/$queueName/messages HTTP/1.1
Host: $AccountId.mns.cn-hangzhou.aliyuncs.com
Date: Wed, 28 May 2012 22:32:00 GMT
x-mns-version: 2015-06-06
Authorization: MNS 15B4D3461F177624206A:xQE0diMbLRepdf3YB+FIEXA****

<?xml version="1.0" encoding="UTF-8"?>
<ReceiptHandles xmlns="http://mns.aliyuncs.com/doc/v1/">
    <ReceiptHandle>1-ODU4OTkzNDU5My0xNDM1MTk3NjAwLTItNg==</ReceiptHandle>
    <ReceiptHandle>1-ODU4OTkzNDU5NC0xNDM1MTk3NjAwLTItNg==</ReceiptHandle>
    <ReceiptHandle>1-ODU4OTkzNDU5NS0xNDM1MTk3NjAwLTItNg==</ReceiptHandle>
</ReceiptHandles>

Response (success)

All three messages are deleted:

HTTP/1.1 204 No Content
x-mns-request-id: 512B2A634403E52B1956****
x-mns-version: 2015-06-06

Response (partial failure)

Two of the three messages fail to delete because they no longer exist in the queue:

HTTP/1.1 404
Connection: close
Content-Type: text/xml;charset=utf-8
Content-Length: 500
x-mns-request-id: 512B2A634403E52B1956****
x-mns-version: 2015-06-06

<?xml version="1.0" encoding="UTF-8"?>
<Errors xmlns="http://mns.aliyuncs.com/doc/v1/">
    <Error>
        <ErrorCode>MessageNotExist</ErrorCode>
        <ErrorMessage>Message not exist.</ErrorMessage>
        <ReceiptHandle>1-ODU4OTkzNDU5My0xNDM1MTk3NjAwLTItNg==</ReceiptHandle>
    </Error>
    <Error>
        <ErrorCode>MessageNotExist</ErrorCode>
        <ErrorMessage>Message not exist.</ErrorMessage>
        <ReceiptHandle>1-ODU4OTkzNDU5NC0xNDM1MTk3NjAwLTItNg==</ReceiptHandle>
    </Error>
</Errors>

Error codes

The following errors are specific to BatchDeleteMessage. For common errors, see Common error codes.

Error code	Error message	HTTP status code	Description
QueueNotExist	The queue name you provided is not exist.	404	The specified queue does not exist. Verify the queue name in the request URL.
InvalidArgument	The value of Element should between Low and High seconds/bytes.	400	A request parameter is outside its valid range. Check that all values meet the documented constraints.
ReceiptHandleError	The receipt handle you provide is not valid.	400	The receipt handle is malformed or has expired. Receive the message again to get a new receipt handle.