A PDF that takes three minutes
A customer asks for a statement of two years of transactions as a PDF, and building it takes about three minutes. This is the whole conversation between the browser and the API when it works:
- The client sends
POST /exportswith the date range. The API answers at once with202 Accepted, aLocationheader pointing at/exports/7f3a/status, andRetry-After: 10. - Ten seconds later the client sends
GET /exports/7f3a/statusand gets200 OK, with a body saying the job is running and 5% done. - About three minutes and many polls later, the same
GETreturns303 See Other, with aLocationpointing at/exports/7f3a/file. - The client follows it and downloads the PDF.
That exchange is Asynchronous Request-Reply: the server accepts the work now and delivers the result later, and all the first response promises is a place to ask. No connection stays open for three minutes. The first version did keep one open, and the load balancer in front of the API, set to drop connections idle for 60 seconds, cut every export off before the PDF was ready. Users clicked again, and each click started another three-minute job whose connection would be cut off too, while the abandoned ones could still be running on the server.
What sits behind the 202
Behind the API, a worker builds the PDF and writes its progress to a job record that every API instance can read; the API creates that record before it answers 202, so the status URL never points at nothing, and the status endpoint only reads it. Both the status URL and the result URL check that the caller owns the job, because the PDF is two years of someone's transactions. The queue that usually carries jobs to the workers belongs to Message queues & async workers. If the API crashes between creating the record and queueing the job, the record waits for a worker that never comes; handing work off reliably after a write is Transactional Outbox.
The API never waits for the worker. The job record is the only thing both of them touch, and every poll reads it.
Two details of the contract matter more than they look. The status response describes the job, not the status request: in the usual design, a job that failed is still answered with 200 OK and a body that says failed and why, because the lookup itself worked. And 202 means only that the request was accepted for processing, not that it will succeed; the client learns the outcome from the status. Inside one program, the same accept-now, result-later idea is a Future / Promise; here the placeholder is a URL.
Asking less often
Each status lookup is cheap, but polls add up: 2,000 exports in progress, each polled every half second by a client that ignores Retry-After, is 4,000 requests a second that mostly learn nothing new. Retry-After is only a hint that nothing enforces, so well-behaved clients honour it and back off as a job runs longer, and the server still has to survive the ones that do not. Server clients can instead pass a callback URL and be called when the job ends (what the receiving side needs is in Webhooks & third-party integration); browsers can hold a push channel, compared in Realtime transport: long-polling vs SSE vs WebSocket. Either way, keep the status endpoint, because callbacks get lost and channels drop, and it is how the client catches up.
Three ways the handshake breaks
The second job. The client sends the POST, the 202 is lost on the way back, and the client, seeing a timeout, sends the POST again. The API cannot tell a retry from a new request, so two workers now build the same PDF. For an export that is wasted work; for an order or a payment it is a duplicate. The client should attach a key that identifies this one request, and the API should answer a repeated key with the status URL of the job it already created. Storing and checking that key safely, including two copies arriving at once, is what Idempotency Key is about.
The job nobody can find. If the job record lives in the memory of the API instance that took the POST, the next poll may land on another instance behind the load balancer, or arrive after a deploy restarted the first one, and get 404. The client cannot tell whether the job failed, never existed or is still running. The record belongs in a store that every instance reads and that survives restarts. It also needs a retention period that clients know about: once a finished job's record and file are deleted, a late poll gets 404 as well.
The job that is always running. A worker crashes halfway through, and the record says running forever. The status needs a way to become true again: the worker holds a lease on the job, an expiry time it pushes forward every few seconds, and something that notices an expired lease marks the job failed or puts it back on the queue. Putting it back means the work can run twice, even at the same time if the first worker was only slow, so its side effects have to tolerate that. That supervisor role has its own pattern, Scheduler Agent Supervisor. The client needs a limit of its own too: after a deadline that matches what the work can reasonably take, it stops polling, which does not cancel the job, and tells the user something more useful than a spinner.
Sketching the handshake
No Challenge asks for this handshake yet, so practise it on a blank Grid: a Client, an Asynchronous Request-Reply node for the API, a Data Store for the job records and a Handler for the worker. Then add the three failures above and the defence against each, the key on the POST, the shared store, the lease. The Online Code Judge challenge has the same accept-now, verdict-later flow, since a submission is queued and its verdict comes later, but its brief does not ask for the handshake, so drawing the 202 and the status endpoint there is up to you.