Acknowledge consumed messages - ApsaraMQ for RocketMQ - Alibaba Cloud Documentation Center

Send a DELETE request to confirm that messages have been successfully processed. After acknowledgment, ApsaraMQ for RocketMQ stops redelivering the messages to the consumer group.

The request body accepts multiple ReceiptHandle elements, which allows you to acknowledge a batch of messages in a single request. Get the ReceiptHandle for each message from the consume messages operation.

Request syntax

DELETE /topics/<TopicName>/messages?ns=<INSTANCE_ID>&consumer=<GID> HTTP/1.1

Request parameters

URI parameters

Parameter	Required	Description
`TopicName`	Yes	Name of the topic to which the messages were sent.
`ns`	No	Instance ID. Required for instances that have a namespace.
`consumer`	Yes	Group ID of the consumer group.

About the ns parameter

ApsaraMQ for RocketMQ has two types of instances:

Default instance: Does not have a namespace. All resource names in a default instance must be globally unique. The ns parameter is not required.
New instance: Has a namespace. Resource names only need to be unique within the instance. The ns parameter is required.

To check whether an instance has a namespace, go to the Instances page in the ApsaraMQ for RocketMQ console. For more information, see Use instances.

Request body (XML)

<?xml version="1.0" encoding="UTF-8"?>
<ReceiptHandles xmlns="http://mq.aliyuncs.com/doc/v1/">
  <ReceiptHandle>receipt-handle-1</ReceiptHandle>
  <ReceiptHandle>receipt-handle-2</ReceiptHandle>
</ReceiptHandles>

Parameter	Required	Description
`ReceiptHandle`	Yes	Message handle returned by the consume messages operation. Used to verify whether a message is successfully consumed. Include one `<ReceiptHandle>` element per message.

Important

Receipt handle constraints:

Single use: Each receipt handle can be used only once. After a successful acknowledgment, the handle is invalidated.
Unique per delivery: Each delivery of the same message produces a different receipt handle, including redeliveries caused by consumption retries. Always use the most recent handle.
Time-limited: A receipt handle expires at the NextConsumeTime returned by the consume operation. Submit the acknowledgment before this deadline, or a MessageNotExist error is returned.

Response

Success

HTTP/1.1 204

No response body is returned.

Failure

HTTP/1.1 404

The response body contains an XML error. See Error codes for details.

Error codes

Error code	HTTP status	Description
`MissingReceiptHandle`	404	The request body does not contain any `ReceiptHandle` elements. Include at least one receipt handle.
`ReceiptHandleError`	404	The receipt handle is malformed or invalid. Verify the handle value returned by the consume operation.
`MessageNotExist`	404	The receipt handle has expired. This happens when the acknowledgment is sent after `NextConsumeTime`. Consume the message again to get a new receipt handle.

Examples

Sample request

DELETE /topics/MyTopic/messages?ns=MQ_INST_1234567890&consumer=GID_test_consumer HTTP/1.1

<?xml version="1.0" encoding="UTF-8"?>
<ReceiptHandles xmlns="http://mq.aliyuncs.com/doc/v1/">
  <ReceiptHandle>1E057D5E6EAD42A57993704EC383****-MTI5NT****</ReceiptHandle>
  <ReceiptHandle>1E057D5E6EAD42A57993704EC383****-MTI5NT****</ReceiptHandle>
  <ReceiptHandle>1E057D5E6EAD42A57993704EC383****-MTI5NT****</ReceiptHandle>
</ReceiptHandles>

Sample success response

HTTP/1.1 204

Sample error responses

Missing receipt handle

<?xml version="1.0"?>
<Error xmlns="http://mq.aliyuncs.com/doc/v1">
  <Code>MissingReceiptHandle</Code>
  <Message>ReceiptHandle is required.</Message>
  <RequestId>5DAEF2B9463541AD6E04490F</RequestId>
  <HostId>http://123.mqrest.cn-hangzhou.aliyuncs.com</HostId>
</Error>

Invalid receipt handle

Error returned when the receipt handle value (adfadfadf in this example) is invalid:

<?xml version="1.0"?>
<Errors xmlns="http://mq.aliyuncs.com/doc/v1">
  <Error>
    <ErrorCode>ReceiptHandleError</ErrorCode>
    <ErrorMessage>The receipt handle you provide is not valid.</ErrorMessage>
    <ReceiptHandle>adfadfadf</ReceiptHandle>
  </Error>
</Errors>

Expired receipt handle

Error returned when the acknowledgment is sent after NextConsumeTime:

<?xml version="1.0"?>
<Errors xmlns="http://mq.aliyuncs.com/doc/v1">
  <Error>
    <ErrorCode>MessageNotExist</ErrorCode>
    <ErrorMessage>The receipt handle you provided has expired.</ErrorMessage>
    <ReceiptHandle>1E057D5E6EAD42A57993704EC383****-MTI5NT****</ReceiptHandle>
  </Error>
</Errors>

ApsaraMQ for RocketMQ:Acknowledge consumed messages