Asynchronous Request-Reply

You order a custom cake. The bakery doesn't make you stand at the counter for three hours while they bake it — they take your order, hand you a ticket number, and tell you to check back later. When you return and your number's up, you collect the cake.

The Asynchronous Request-Reply pattern is that bakery ticket, for APIs. Some operations are just too slow to finish inside a single HTTP request. Rather than holding the connection open and hoping it doesn't time out, you accept the request immediately, hand back a ticket, and let the caller check back for the result.

The problem

HTTP is built for quick, synchronous exchanges: send a request, get a response, done. But plenty of real work — generating a report, transcoding a video, running a big calculation — takes seconds or minutes. Try to do it inside one request and everything fights you: browsers and load balancers time out after 30–60 seconds, the connection ties up a server thread the whole time, and a network blip means the client has no idea whether the work finished or not.

The nastiest part is that a timeout only closes the connection. The server usually keeps working, because nothing tells it to stop. Step through one report that takes about 90 seconds. First predict what the timeout does to the work; then, when the client is left holding a bare 504, decide what it should do and see where that leads.

A long report behind a 30-second timeout

The client asks for a report with POST /reports. The API starts , about 90 seconds of work, while the client waits on an .

Predict first

The gateway closes any connection that has been open for 30 s. What happens at t = 30 s?

1 / 5

Read all steps as text

Request. The client asks for a report with POST /reports. The API starts building it, about 90 seconds of work, while the client waits on an open connection.Question: The gateway closes any connection that has been open for 30 s. What happens at t = 30 s? Answer: The client gets an error, but the job keeps running. The gateway only closes the connection. Nothing tells the API to stop, so it keeps building a report that now has nowhere to go.
504. At 30 s the gateway gives up and sends the client 504 Gateway Timeout. The API is never told: job 1 keeps running.Choice: All the client knows is “504”. What should it do? Options: Retry the request / Give up and show an error. Neither is safe: the client can't tell whether the report failed, is still being built, or is already done.
Retry. The client retries. To the API it's a brand-new request, so it starts job 2 while job 1 is still running. Same report, built twice.
504 again. 30 s later the retry hits the same limit: another 504. Two jobs are running for one report, and the client still has nothing.
Report lost. At 88 s job 1 finishes, but its connection closed long ago and the client has given up, so the report is thrown away. Job 2 will end the same way. Twice the work, no report.

Either way, the client is stuck because it has no handle on the job: no way to ask "how is the report I asked for doing?" You can't just make the slow thing fast. So instead of pretending the call is quick, you need a way to break the link between asking for the work and waiting for it to complete.

How it works

The flow has three steps. First, the client sends the request and the API accepts it immediately — it validates the input, drops a job onto a queue, and responds with 202 Accepted plus a status URL (the ticket) in the Location header. The connection closes in milliseconds.

Second, a background worker picks the job off the queue and does the heavy lifting at its own pace, completely decoupled from the original caller. Third, the client polls the status URL: it gets 200 OK with "still working" until the job finishes, at which point the status endpoint points to the finished result (often a 303 See Other redirect to the result resource).

Step through the same report, asynchronous this time. Predict what the very first call returns before you look. Then flip to Synchronous at any step to see the old approach at the same moment.

Accept fast, work in the background, poll for the answer

The same report, about 90 seconds of work, but asynchronous this time. The client sends POST /reports.

Predict first

What does the client get back from this first call?

1 / 6

Read all steps as text

Request. The same report, about 90 seconds of work, but asynchronous this time. The client sends POST /reports.Question: What does the client get back from this first call? Answer: 202 Accepted and a status URL, in a fraction of a second. The API doesn't build the report inside the request. It checks the input, queues the job and answers at once: 202 Accepted, plus a status URL to check later.
202 + ticket. A tenth of a second later the client holds its ticket: 202 Accepted, with the status at /status/42. The API has put job 42 on a queue and a worker has started it. The connection is already closed.
Poll: 34%. At 30 s the client polls the status URL and hears running, 34%. Each poll takes milliseconds, so the 30-second gateway limit never comes close.
Poll: 68%. Another poll at 60 s: 68%. The worker goes at its own pace, and no client connection is held open while it does.
Job done. At 88 s the worker finishes and saves the report. Nobody tells the client: it finds out on its next poll, so the poll interval adds a little delay.
303 → report. The poll at 90 s returns 303 See Other, pointing to /reports/42. The client follows it and downloads the report. Four short calls, one job, no timeouts.

Tip

Make accepting a job idempotent. A client that times out before getting its 202 will retry — and you don't want to start the same expensive job twice. Key the request so a retry returns the existing job's status URL instead of creating a duplicate.

Check yourself

Your API returns 202 Accepted with a status URL, yet some users get the same report generated twice. What's the most likely cause?

Designing the status endpoint

The status URL is the contract between client and server, so a few details matter:

Tell clients how often to ask. Send a Retry-After header with the 202 and with each "still running" reply. Without it, eager clients poll every few milliseconds and the status endpoint takes more load than the real work.
Report failure, not just progress. The status must be able to say failed, with a reason, so the client can stop polling and tell the user.
Keep status and result separate. The status resource describes the job; the result lives at its own URL. When the job finishes, the status endpoint redirects there, and the result can be cached or downloaded like any other resource.
Clean up. Finished results and old job records should expire after a while, and a DELETE on the status URL is a natural way to let clients cancel a job they no longer need.

Watch out

A status that can only say "running" is a trap. If a worker crashes halfway through and nothing records it, the job's status stays "running" forever — and every client polls forever. Give each job a deadline, record failures where the status endpoint can see them, and only return 202 once the job is safely on the queue, so the ticket never points at work that was silently lost.

When to use it

Use this pattern whenever an operation is too slow to fit comfortably in a single request but the client still needs the eventual result — report generation, media processing, bulk imports, anything compute-heavy. It keeps your front-end connections short and snappy, and lets the background work scale independently behind a queue with competing consumers.

Skip it when the work is genuinely fast; the extra machinery and the polling protocol aren't worth it for a 50-millisecond query. And if the client can't poll — or you'd rather push the result the moment it's ready — consider webhooks, WebSockets, or server-sent events instead. Async request-reply is the simplest fit when the client is happy to come back and ask, "Is it done yet?"

Check yourself

A worker crashed halfway through job 42. A day later a client is still polling /status/42 and hearing "running". What was missing?

Asynchronous Request-Reply

The problem

How it works

Designing the status endpoint

When to use it

Key takeaways

Keep going