---
title: "Concepts"
description: "Queues and their settings, messages, the life of a message, visibility timeouts, receipt handles, long polling and retention."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.ezghcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Concepts

## Terms

| Term | Meaning |
| --- | --- |
| Queue | A named store of messages in a project, `standard` or `fifo`. Its ID is a UUID, and its slug starts with `que_`. Its name (1 to 80 letters, digits, `-` and `_`) is unique in the project. The name and type are fixed at creation. |
| Message | A UTF-8 text body and up to 10 string attributes, at most 256 KiB together. Each has a UUID `messageId` assigned when it's sent. |
| Receive | A consumer's request for up to 10 messages. Received messages are **in flight**: hidden from other consumers until they're acknowledged or their visibility timeout ends. |
| Receipt handle | An opaque string returned with each received message. It acknowledges the message, or changes its visibility timeout, for that delivery only. |
| Subscription | A queue's managed consumer: Queues pushes its messages in batches to your HTTPS endpoint. A queue has at most one. Its slug starts with `qsb_`. See [Push subscriptions](/queues/push). |
| Dead-letter queue | A queue that another queue's redrive policy names: messages received too many times move there. See [Dead-letter queues](/queues/dead-letter-queues). |

## Standard and FIFO queues

| | Standard | FIFO |
| --- | --- | --- |
| Delivery | At least once: a message can be delivered more than once | At least once, in order within each message group |
| Order | Best effort | Strict per message group (`groupId`, required on every send) |
| Duplicate sends | Stored again | Not stored again within 5 minutes of a send with the same `dedupId` |
| Delay per message | `delaySeconds` on each message, or the queue's | The queue's `delaySeconds` only |
| Throughput | 3,000 send and 3,000 receive requests a second per queue, by default | 300 of each a second per queue, by default; one group's messages are handled one batch at a time |

Write consumers so handling a message twice is harmless, on either type: a consumer can crash
after doing the work and before acknowledging it. See [FIFO queues](/queues/fifo) for groups and
deduplication.

## Queue settings

| Setting | Default | Range | Meaning |
| --- | --- | --- | --- |
| `visibilityTimeoutSeconds` | 30 | 0 to 43,200 (12 hours) | How long a received message stays hidden from other consumers |
| `retentionSeconds` | 345,600 (4 days) | 60 to 1,209,600 (14 days) | How long a message is kept after it's sent |
| `delaySeconds` | 0 | 0 to 900 | How long a new message waits before it can be received |
| `receiveWaitSeconds` | 0 | 0 to 20 | How long a receive waits for messages when it doesn't say |
| `redrive` | `null` | `{ "deadLetterQueue": "<queue id>", "maxReceiveCount": 1–1000 }` | Where messages go after `maxReceiveCount` receives |
| `contentBasedDedup` | `false` | FIFO only | Deduplicate sends without a `dedupId` by their body |

Change them with [UpdateQueue](/queues-api/UpdateQueue/). A new visibility timeout applies
to receives from then on, and a new retention to messages sent from then on: messages already in
flight keep their deadlines. `"redrive": null` removes the redrive policy.

## The life of a message

1. **Sent.** [SendMessages](/queues-api/SendMessages/) stores it. With a delay it's
   **delayed**; otherwise it's **visible** at once.
2. **Received.** A receive claims it and returns it with a receipt handle. It's **in flight**
   for the visibility timeout, and its `receiveCount` goes up by one.
3. **Then one of these:**
- **Acknowledged** with its receipt handle: it's deleted.
- **Released** (its visibility changed to 0), or its visibility timeout ends: it's visible
     again, and the next receive gets it.
- **Dead-lettered:** a receive finds it has already been received `maxReceiveCount` times, and
     moves it to the dead-letter queue instead of returning it.
- **Expired:** its queue's retention ends, counted from when it was sent, received or not.
- **Purged,** or deleted with its queue.

A queue's `counts` give the messages in each state: `visible`, `inFlight` and `delayed`. They're
approximate, and exact up to 100,000 each; beyond that `truncated` is `true`.

## Visibility timeouts

The visibility timeout is how long a consumer has to handle a message before another consumer can
receive it. Set it longer than your consumer usually takes:

- **Per queue**, with `visibilityTimeoutSeconds`.
- **Per receive**, with the receive's own `visibilityTimeoutSeconds`.
- **Per message, after receiving it,** by [changing its visibility](/queues/consumers#extend-or-release-a-message):
  a consumer that needs longer extends it, and one that can't handle a message releases it at
  once with `0`.

A message stays in flight for at most 12 hours from the receive, however often it's extended.

## Receipt handles

Each receive of a message returns a new receipt handle. A handle:

- **Acknowledges the message or changes its visibility** on `https://queues-live.ezghcloud.com`,
  without a credential. Treat handles as you would a credential for that one message.
- **Works for that delivery only.** Once the message is received again, acknowledged, moved to a
  dead-letter queue, purged or expired, the handle is stale: using it fails with
  `receipt_handle_stale` and changes nothing.
- **Still works after the visibility timeout ends,** until another receive takes the message.

So a consumer that loses its access can still acknowledge or extend messages it already holds,
until they're received again; it can't receive new ones.

## Long polling

A receive with `waitSeconds` above 0 is a long poll: it answers as soon as messages are available,
or with an empty list when the wait ends. Long polls answer within moments of a send, so consumers
don't need to poll in a loop with sleeps, and an empty answer costs one request per wait instead
of many. Use `waitSeconds: 20`, or set the queue's `receiveWaitSeconds` to 20 so every receive
waits.

## Purging and deleting

- **[PurgeQueue](/queues-api/PurgeQueue/)** deletes every message sent before the purge,
  in flight or not; messages sent after it are kept. They disappear at once and are deleted in the
  background. A queue can be purged once every 60 seconds.
- **[DeleteQueue](/queues-api/DeleteQueue/)** deletes the queue, its subscription and its
  messages. Waiting receives answer `404`, and the messages' receipt handles become stale. A queue
  that another queue names as its dead-letter queue can't be deleted (`409 queue_in_use`):
  remove that redrive policy first.

## Partitions

A queue's `partitions` is 1 when it's created. Queues raises it, up to 64, when the queue's send
rate grows, so busy queues spread their messages without any setting. On a FIFO queue a message
group never splits across partitions, so its order holds.

Source: https://docs.ezghcloud.com/queues/concepts/index.mdx