How do I troubleshoot ReceiptHandleIsInvalid and InvalidParameterValue errors when calling the AWS SQS DeleteMessage API?

Short description

Every time you receive a message from an Amazon SQS queue, you receive a receipt handle for the message. The handle is associated with the action of receiving the message rather than the message itself. To delete the message, you must provide the receipt handle.

The error message varies depending on whether you use FIFO queues or standard SQS queues, and whether the receipt handle is incorrect or expired.

FIFO SQS queues

If the receipt handle is incorrect, then you see an error similar to the following:

An error occurred (ReceiptHandleIsInvalid) when calling the DeleteMessage operation: The input receipt handle 'YOUR RECEIPT HANDLE' is not a valid receipt handle.

For FIFO queues, a receipt handle expires after a visibility timeout period. When a receipt handle expires, the message returns to the queue. When you receive the message again, you get a new receipt handle. If you try to delete the message outside of the visibility timeout period, then you see an error similar to the following:

An error occurred (InvalidParameterValue) when calling the DeleteMessage operation: Value 'YOUR RECEIPT HANDLE' for parameter ReceiptHandle is invalid. Reason: The receipt handle has expired.

Standard SQS queues

If the receipt handle is incorrect, then you see an error similar to the following:

An error occurred (ReceiptHandleIsInvalid) when calling the DeleteMessage operation: The input receipt handle 'YOUR RECEIPT HANDLE' is not a valid receipt handle.

For standard queues, you might sometimes succeed in using an older receipt handle. However, it’s a best practice to use the latest receipt handle for DeleteMessage API calls. Using an older receipt handle can result in an error similar to the following:

An error occurred (InvalidParameterValue) when calling the DeleteMessage operation: Value 'YOUR RECEIPT HANDLE' for parameter ReceiptHandle is invalid. Reason: The receipt handle has expired.

Resolution

To prevent invalid or expired receipt handle errors, you must delete the message within the SQS queue visibility timeout period using the correct receipt handle.

If you receive a message more than once, review the most recent ReceiveMessage API call response and identify the ReceiptHandle value. Then, use the identified ReceiptHandle value when you call the DeleteMessage API.

Related information

ReceiveMessage

DeleteMessage