Message delivery
How a message travels through a queue, from send to delete, and what the visibility timeout, receipt handles, long polling, delays and retention do to it.
This page describes a standard queue. A FIFO queue follows the same steps with stricter ordering; see FIFO queues.
From send to delete
- Send. The message is stored. With a delay (the queue's delivery delay, or on a standard queue a delay given with the send), it cannot be received until the delay has passed.
- Receive. A receive takes up to 10 messages (1 unless you ask for more) and hides each one for the visibility timeout: the queue's (30 seconds on a new queue), or the one the receive names. Each message comes with a receipt handle and its receive count.
- Delete. Your consumer deletes the message with the receipt handle once the work is done.
- If it does not, the message becomes receivable again when the visibility timeout ends, and the next receive delivers it again with a new receipt handle.
At-least-once delivery
A message is delivered until it is deleted or expires. The same message can arrive twice, for example when a consumer takes longer than the visibility timeout. Make processing idempotent.
Order is best effort: a receive takes the messages that have been receivable longest first, but there is no guarantee. Use a FIFO queue when order matters.
Receipt handles
Every receive issues a new receipt handle. Only the handle of the latest receive deletes or changes
the message, so a consumer whose time ran out cannot delete work that another consumer now holds:
a delete with an older handle is refused with ReceiptHandleIsInvalid, and a visibility change
with MessageNotInflight. Deleting a message that is already gone (deleted or expired) succeeds,
so a retried delete is safe.
Long polling
A receive can wait up to 20 seconds for a message (waitSeconds, or WaitTimeSeconds from an SQS
client). It answers as soon as a message arrives, or empty when the time is up. A receive that
names no wait uses the queue's receive wait, which is 0 (answer at once) on a new queue. Long
polling means fewer requests, and a long poll is billed as one request however long it waits.
Retention
A message that is not deleted is kept for the queue's retention (4 days on a new queue, 1 minute to 14 days), counted from when it was sent. A message keeps the expiry it was sent with: changing the retention affects messages sent afterwards. An expired message is never delivered again and is removed.
Message counts
| Count | Meaning |
|---|---|
| Available | Receivable now. |
| In flight | Received at least once and hidden by a visibility timeout that is running. |
| Delayed | Sent with a delay that has not passed yet, and never received. |