Visibility Timeout

When a consuming component in your system receives and processes a message from the queue, the message remains in the queue. Why doesn't SQS automatically delete it?

Because your system is distributed, there's no guarantee that the component will actually receive the message (it's possible the connection could break or the component could fail before receiving the message). Therefore, SQS does not delete the message, and instead, your consuming component must delete the message from the queue after receiving and processing it.

Immediately after the component receives the message, the message is still in the queue. However, you don't want other components in the system receiving and processing the message again. Therefore, SQS blocks them with a visibility timeout, which is a period of time during which SQS prevents other consuming components from receiving and processing that message. The following figure and discussion illustrate the concept.

Visibility Timeout

The visibility timeout clock starts ticking once SQS returns the message. During that time, the component processes and deletes the message. But what happens if the component fails before deleting the message? If your system doesn't call DeleteMessage for that message before the visibility timeout expires, the message again becomes visible to the ReceiveMessage calls placed by the components in your system and it will be received again. If a message should only be received once, your system should delete it within the duration of the visibility timeout.

Each queue starts with a default setting of 30 seconds for the visibility timeout. You can change that setting for the entire queue. Typically, you'll set the visibility timeout to the average time it takes to process and delete a message from the queue. When receiving messages, you can also set a special visibility timeout for the returned messages without changing the overall queue timeout.

We recommend that if you have a system that produces messages that require varying amounts of time to process and delete, you create multiple queues, each with a different visibility timeout setting. Your system can then send all messages to a single queue that forwards each message to another queue with the appropriate visibility timeout based on the expected processing and deletion time for that message.

The following table lists the API actions to use to manipulate the visibility timeout.

To do this... Use this action

Set the visibility timeout for a queue

SetQueueAttributes

Get the visibility timeout for a queue

GetQueueAttributes

Set the visibility timeout for the received messages without affecting the queue's visibility timeout

ReceiveMessage and set the VisibilityTimeout parameter to the value you want