Delivery guarantees
A delivery guarantee says how many times a message can reach its consumer. With at-least-once delivery, a job that gets no acknowledgment within the 30 s visibility timeout goes out again. So the consumer must handle the same job twice.
See it on the board
The same traffic runs on two boards. The simulator measured both when this page was built.
| Measure | Goal | Payment runs again on each repeated delivery | Payment provider checks an idempotency key |
|---|---|---|---|
| Duplicates | none | 200 Fail | 0 Pass |
| Completion time | under 40 s | 10.1 s Pass | 10.1 s Pass |
| Lost writes | none | 0 Pass | 0 Pass |
| Monthly cost | 12 USD/mo | 12 USD/mo | |
| Error rate | 0% | 0% |
Key numbers
| Number | Value |
|---|---|
| Time before an unacknowledged job goes out again | 30 s |
| Deliveries of one job before it stops, default | 5 deliveries |
| Jobs one consumer can hold at once, default | 20 jobs |
| Call to the payment provider, median | 150 ms |
13 deliveries · 10 payments applied · 0 charged twice
How it works
A queue and its consumer agree on delivery through acknowledgments. The consumer takes a job, does the work, then sends an ack. Only then does the queue delete the job.
The order of these steps sets the guarantee. At most once: the queue deletes the job when it sends it. A crash in the consumer loses the job, but the job never runs twice. At least once: the queue keeps the job until the ack arrives. If the consumer crashes, the ack is lost, or the work takes longer than the visibility timeout, the queue sends the job again. No job is lost, but some jobs run twice.
Exactly once is not a property of the network. You get its effect when at-least-once delivery meets a consumer that ignores repeats, for example with an idempotency key that it stores with the result.
A limit on deliveries protects the system from a job that always fails. After the last try, the queue moves the job to a dead letter queue, where a person or a tool can examine it. Without that limit, one bad job can block a consumer forever.
In the levels you choose the delivery mode, set the timeouts and make repeated jobs safe.