An order API Worker returns 202 and calls env.ORDERS.send() inside ctx.waitUntil(); some orders never reach the Cloudflare queue. Why, and what is the fix?
answer
- when the send promise resolves
- who sees a rejected promise
- throughput, size and backlog limits
- answer the client after the write
basics
~20 sInside ctx.waitUntil(), a rejected send() is never seen: the client already got 202 and Cloudflare ignores the error. Await env.ORDERS.send() before responding, since it resolves only once the message is on disk, and return an error status when it throws.
solid answer
~40 s`send()` and `sendBatch()` return a promise that resolves when Queues has written the message to disk and rejects when the write fails. `ctx.waitUntil()` only keeps the Worker alive until that promise settles; nothing handles the rejection, so the failure is lost while the client already holds a `202`. Writes fail for real reasons: more than 5,000 messages per second on one queue throws `Too Many Requests`, a backlog at the 25 GB limit returns `Storage Limit Exceeded`, and a body over 128 KB or a 101-message `sendBatch()` is rejected. The fix is to `await env.ORDERS.send(order)` inside a `try`, answer `202` only after it resolves, and return `503` (or the size error) when it throws, so the client can retry. Use `sendBatch()` when one request produces several messages.
code
javascript · 12 linesexport default {
async fetch(request, env, ctx) {
const order = await request.json();
try {
await env.ORDERS.send({ orderId: order.orderId, total: order.total });
} catch (err) {
console.error("enqueue failed", order.orderId, err.message);
return new Response("try again", { status: 503, headers: { "Retry-After": "5" } });
}
return new Response("accepted", { status: 202 });
},
};go deeper
Remember that send() returns a promise that resolves once the message is stored, and that it should be awaited.
Explain why errors from a send() inside ctx.waitUntil() are ignored, and name the limits that make sends fail.
Diagnose silent loss under load from the throughput and backlog limits, and restructure the handler to await, map failures to 503 and keep client retries safe.
Decide which messages justify the extra response latency of an awaited write and which may go through waitUntil, and make that rule part of API review.
## What "accepted" has to mean An **order-ingestion API** that answers `202 Accepted` is promising that the order will be processed. With **Cloudflare Queues**, that promise is only true once the message is stored. The producer binding's `send()` and `sendBatch()` methods return promises that **resolve when the message is confirmed written to disk** and **reject** when it is not. The response must therefore wait for that promise. ## Why ctx.waitUntil() hides the failure `ctx.waitUntil(promise)` tells the runtime to keep the invocation alive after the response until `promise` settles. It is meant for work the client does not need to wait for, such as logging. It does not report the outcome anywhere, and the Queues documentation says it plainly: because `waitUntil()` is non-blocking, any errors raised from `send()` or `sendBatch()` are **implicitly ignored**. Put together, the failing handler does this: 1. It returns `202` immediately. 2. `send()` runs in the background and rejects. 3. The rejection goes nowhere and the order is lost, while the client believes it succeeded and will not retry. ## Why sends fail in practice | Cause | Limit | What the producer sees | |---|---|---| | Throughput | 5,000 messages per second per queue | `send()` and `sendBatch()` throw a `Too Many Requests` error until the rate drops | | Backlog | 25 GB per queue | `send()` and `sendBatch()` get a `Storage Limit Exceeded` error | | Message size | 128 KB per message, about 100 bytes of metadata included | the message is rejected | | Batch size | 100 messages or 256 KB per `sendBatch()` call | the whole call is rejected | | Body type | the declared `contentType` | a `TypeError` before anything is written | The throughput and backlog failures are the dangerous ones because they appear under load, precisely when many orders are in flight; a stalled consumer is what typically fills a backlog. ## The fix - **Await the write before answering.** `await env.ORDERS.send(order)` inside `try`; return `202` only after it resolves. - **Turn failures into a retryable status.** On a thrown error, return `503` with a `Retry-After` header so the client retries; reject an order body too large to enqueue with `413` before calling `send()`. - **Batch fan-out writes.** When one request yields several messages, one `sendBatch()` call is one round trip and one promise to check, instead of several calls that can partly succeed. - **Keep waitUntil for the optional work.** Analytics, audit logs and cache warm-ups can still go through `ctx.waitUntil()`. - **Make the client's retry safe.** A client that retries after a `503` may resend an order whose first write actually landed, so the consumer should deduplicate on the order ID the client supplies. ## Reviewing producer code A short checklist catches this class of bug before it ships: 1. Every `send()` and `sendBatch()` on a path that answers a client is awaited, or sits in `ctx.waitUntil()` with a written reason why losing it is acceptable. 2. Fan-out writes are split into `sendBatch()` calls of at most 100 messages and 256 KB. 3. Bodies that could approach 128 KB are measured, and large payloads go to object storage with only a reference in the message. 4. A thrown send maps to a status the client will retry, and the body carries a client-supplied order ID so the retry is harmless. ## Watching for it A missing order is invisible in the Worker's own metrics when the error is swallowed. After the fix, failures show up as `503` responses and logged errors in Workers Logs. The binding's `metrics()` method, and the `metadata.metrics` object returned by each send, report `backlogCount` and `backlogBytes`, which give early warning that the queue is approaching its backlog limit because the consumer has fallen behind. ## Latency is the trade Awaiting the send adds the write's round trip to the API's response time. That is the cost of a `202` that means something; the background path is only acceptable for messages the business can afford to lose, such as best-effort analytics events. When the latency matters, the usual fix is to make the message smaller or to batch several writes into one `sendBatch()`, not to stop awaiting it. Under a throughput limit, the other lever is spreading traffic over several queues, since the 5,000 messages per second limit applies per queue.
- Why not keep the background send and simply add a .catch() that logs the error?Logging makes the loss visible, but the order is still lost: the client already holds a `202` and will not retry. A `.catch()` inside `ctx.waitUntil()` can only record the failure or try again within the same invocation's remaining time. Only awaiting before responding lets the client learn the order was not accepted.
- One API request produces five order-line messages. Why prefer one sendBatch() call over five send() calls?`sendBatch()` writes all five in one round trip, and one promise reports the outcome of the call. Five `send()` calls can partly succeed, leaving the API to decide what a half-enqueued order means. A call is limited to 100 messages and 256 KB in total, so larger fan-outs are split into several calls.
- ctx.waitUntil() retries a rejected send() automatically.
- Once send() is called the message is durable, awaited or not.
- Queues has no throughput limit, so send() never fails under load.
- A failed background send shows up as a 500 to the client.
- Returning 202 before the write is fine because Queues guarantees delivery.