1# Cloudflare Queues
2 
3Flexible message queuing for async task processing with guaranteed at-least-once delivery and configurable batching.
4 
5## Overview
6 
7Queues provide:
8- At-least-once delivery guarantee
9- Push-based (Worker) and pull-based (HTTP) consumers
10- Configurable batching and retries
11- Dead Letter Queues (DLQ)
12- Delays up to 12 hours
13 
14**Use cases:** Async processing, API buffering, rate limiting, event workflows, deferred jobs
15 
16## Quick Start
17 
18```bash
19wrangler queues create my-queue
20wrangler queues consumer add my-queue my-worker
21```
22 
23```typescript
24// Producer
25await env.MY_QUEUE.send({ userId: 123, action: 'notify' });
26 
27// Consumer (with proper error handling)
28export default {
29  async queue(batch: MessageBatch, env: Env): Promise<void> {
30    for (const msg of batch.messages) {
31      try {
32        await process(msg.body);
33        msg.ack();
34      } catch (error) {
35        msg.retry({ delaySeconds: 60 });
36      }
37    }
38  }
39};
40```
41 
42## Critical Warnings
43 
44**Before using Queues, understand these production mistakes:**
45 
461. **Uncaught errors retry ENTIRE batch** (not just failed message). Always use per-message try/catch.
472. **Messages not ack'd/retry'd will auto-retry forever** until max_retries. Always explicitly handle each message.
48 
49See [gotchas.md](./gotchas.md) for detailed solutions.
50 
51## Core Operations
52 
53| Operation | Purpose | Limit |
54|-----------|---------|-------|
55| `send(body, options?)` | Publish message | 128 KB |
56| `sendBatch(messages)` | Bulk publish | 100 msgs/256 KB |
57| `message.ack()` | Acknowledge success | - |
58| `message.retry(options?)` | Retry with delay | - |
59| `batch.ackAll()` | Ack entire batch | - |
60 
61## Architecture
62 
63```
64[Producer Worker] → [Queue] → [Consumer Worker/HTTP] → [Processing]
65```
66 
67- Max 10,000 queues per account
68- 5,000 msgs/second per queue
69- 4-14 day retention (configurable)
70 
71## Reading Order
72 
73**New to Queues?** Start here:
741. [configuration.md](./configuration.md) - Set up queues, bindings, consumers
752. [api.md](./api.md) - Send messages, handle batches, ack/retry patterns
763. [patterns.md](./patterns.md) - Real-world examples and integrations
774. [gotchas.md](./gotchas.md) - Critical warnings and troubleshooting
78 
79**Task-based routing:**
80- Setup queue → [configuration.md](./configuration.md)
81- Send/receive messages → [api.md](./api.md)
82- Implement specific pattern → [patterns.md](./patterns.md)
83- Debug/troubleshoot → [gotchas.md](./gotchas.md)
84 
85## In This Reference
86 
87- [configuration.md](./configuration.md) - wrangler.jsonc setup, producer/consumer config, DLQ, content types
88- [api.md](./api.md) - Send/batch methods, queue handler, ack/retry rules, type-safe patterns
89- [patterns.md](./patterns.md) - Async tasks, buffering, rate limiting, D1/Workflows/DO integrations
90- [gotchas.md](./gotchas.md) - Critical batch error handling, idempotency, error classification
91 
92## See Also
93 
94- [workers](../workers/) - Worker runtime for producers/consumers
95- [r2](../r2/) - Process R2 event notifications via queues
96- [d1](../d1/) - Batch write to D1 from queue consumers
97