esc
  • WorkflowsPages
  • Case studiesPages
  • Machine Learning FoundationsLearn
  • AI EngineeringLearn
  • AI Guardrails & Red TeamingLearn
  • UI/UXLearn
  • Design SystemsLearn
  • Production System DesignLearn
  • Book a callContact
  • Download ResumeContact
Let’s talk

I’ll build the agent for it.

Async Request Reply: Accept the Job Now, Report Back Later

Long jobs get a quick 202 reply and a status link, so the client never waits on one open connection.

In short

Async Request Reply accepts a long job right away with a quick 202 reply and a status link, so the client never waits on one open connection.

13 min readFree

What You Will Learn

Some work takes longer than a web request should wait. Exporting a year of sales data, converting a large video, or building a big report can take seconds or minutes. This lesson covers Async Request Reply, a design pattern that splits one job into two steps. The server accepts the job right away, and the client checks back later to collect the result. By the end you should be able to explain why waiting fails, walk through the reply flow, and decide when the pattern is worth its extra work.

Key words

Synchronous call
A request where the caller waits, with the connection open, until the answer is ready.
Timeout
A time limit. When it passes, the caller stops waiting and reports an error.
HTTP
The set of rules that browsers and servers use to send requests and replies on the web.
HTTP 202 Accepted
A status code meaning the server got the request and intends to act on it, but the work is not guaranteed to be finished.
Status endpoint
A web address you can ask for the current state of a job.
Polling
Asking the same address again and again until the job reports that it is done.
Location header
A field in an HTTP reply that holds a web address. Here it points to the status address.
Idempotent
Safe to repeat. Sending the same request twice has the same effect as sending it once.
Webhook
A web address the client gives the server, which the server calls when a job ends.

Why Does Waiting Fail?

Most web calls finish in well under a second. The usual design is synchronous: the client sends a request, the server does the work, and the reply comes back on the same connection. That works well when the work is short. It breaks when the work takes a long time, for three reasons.

  • Waiting too long

    Proxies and load balancers often give up after a set time, and most HTTP client libraries apply a timeout too. When that limit passes, the user sees an error, even if the server is still working and would have finished a minute later.

  • Blocked connections

    Each waiting call holds a connection and a worker on the server. If many slow calls pile up, quick requests from other users queue behind them.

  • Lost replies

    If the connection drops during the wait, the client cannot tell whether the server ever got the request or finished the work. A retry can then run the work twice.

The fix is not to make the server faster. The fix is to stop holding the connection open while the work runs. The server takes the job, promises to do it, and gives the client a receipt it can check later.

What a timeout does to a user. Picture someone who clicks Export and watches a spinner. After the browser gives up, the page shows a red error. The report may be finished on the server, but the user cannot reach it. So they click again, and a second job starts. Async Request Reply prevents this loop by giving the user a status address that can be checked calmly.

What Is the Four-step Flow?

The pattern turns one slow call into a short exchange. The client makes four moves, and each move has one clear job.

  1. 1

    Send the request

    The client calls the API once with the job details, such as the date range and the file format.

  2. 2

    Get a 202 right away

    The server checks the request, saves a job record marked pending, starts the work in the background, and replies with 202 Accepted. The reply includes a Location header that points to the job's status address.

  3. 3

    Poll the status endpoint

    The client asks the status address for the current state. While the job runs, the answer says so. The reply uses 200 OK, because the status check itself worked.

  4. 4

    Fetch the result

    When the job completes, the status address sends the client on to the finished result, using a redirect such as 303 See Other. The client then loads that result with a normal GET request.

Notice that there are two kinds of success here. The 202 means the job was accepted. The 200 on a status check means the status check worked. Neither one means the report is ready. Only the final redirect or result means that.

Reading the 202 response. A good 202 answers three questions: where to check, how often to check again, and what the job is called. Many servers put the status address in the Location header. Some also send a Retry-After header, which hints when the client should check next. The body often holds a job ID, so the client can keep track of which job is which.

Tip

Check the request before you accept it. If the request is broken, for example a missing file format, reply at once with 400 Bad Request and do not create a job.

Text
POST /exports HTTP/1.1
Host: api.example.com
Content-Type: application/json

{"from": "last-12-months", "format": "csv"}

HTTP/1.1 202 Accepted
Location: /jobs/abc123
Retry-After: 10
Content-Type: application/json

{"job_id": "abc123", "status": "pending"}

How Does the Client Get the Result?

A status answer should say plainly where the job stands. A common set of states is pending, running, complete, and failed. A job can also be canceled. The client reads the state and acts on it: keep waiting, show progress, show the result, or show a clear error.

  • Pending or running

    The job is saved, and either no worker has picked it up yet or work is in progress. A progress number helps the user, if the server can estimate one.

  • Complete

    The result is ready. The status answer leads to the final resource, such as a download address, so the client can fetch it.

  • Failed

    The status answer carries a structured error the client can show or log. The client should never be left guessing.

Polling is the simplest way to learn the result. It also gives the client control, because the client decides when to ask. The status address remains the source of truth, even when other ways of notifying the client are added.

How Do You Choose a Polling Interval?

Polling too often wastes server work. Polling too rarely makes the user wait longer than needed. A sensible approach is to start with a modest gap, use the Retry-After hint when the server sends one, and lengthen the gap for jobs that run a long time. Treat those numbers as starting points, not rules.

Tip

Never poll in a tight loop. Checking every few milliseconds adds load to the server and gives the user nothing new.

Webhooks and Other Ways to Avoid Polling

Polling is not the only option. With a webhook, the client gives the server a callback address when it submits the job, and the server calls that address when the job ends. This saves repeated checks. The cost is that the client must expose a secure public address and verify that each call really came from the server. Some systems use server-sent events or push notifications instead. Many teams keep polling as the base method and add a webhook as an extra.

Worked Example: A Yearly Export

Imagine an analytics dashboard with a button labeled Export as CSV. A manager picks the last twelve months and clicks the button. Building the file reads a large table, so it takes a few minutes. Here is the flow, step by step.

  1. 1

    Click

    The dashboard sends one POST request to the export API with the date range and the CSV format.

  2. 2

    Immediate 202

    The server checks the dates, saves an export job as pending, and replies in well under a second with 202 Accepted. The Location header gives the job's status address.

  3. 3

    Screen shows progress

    The dashboard shows the words 'Preparing your report...' The page stays usable, so the manager can keep working while the file builds.

  4. 4

    Poll

    The dashboard checks the status address at a set interval. Each answer says running, and the progress number moves upward.

  5. 5

    Download link appears

    When the job completes, the status answer includes a link to the finished CSV. The dashboard swaps the message for a Download button.

  6. 6

    Failure path

    If the export fails, the status answer says failed with a short reason, and the screen offers to try again.

The code below plays the server side of this flow in a few lines. It is a simulation, not a real web server. Each status check counts as one poll, and the job completes on the third check. The first line is the 202 reply with its Location address. The next three lines are the status answers.

Python
import json

jobs = {}

def submit():
    jobs['1'] = {'status': 'pending', 'checks': 0}
    return 202, {'Location': '/jobs/1'}

def check(job_id):
    job = jobs[job_id]
    job['checks'] += 1
    if job['checks'] >= 3:
        job['status'] = 'complete'
        job['result'] = '/reports/1.csv'
    body = {'status': job['status']}
    if job['status'] == 'complete':
        body['result'] = job['result']
    return 200, body

code, headers = submit()
print(code, headers['Location'])
for _ in range(3):
    code, body = check('1')
    print(code, json.dumps(body, sort_keys=True))

Output

202 /jobs/1
200 {"status": "pending"}
200 {"status": "pending"}
200 {"result": "/reports/1.csv", "status": "complete"}

Look at the final line. The status check returns 200, and the body now holds the address of the finished file. The dashboard turns that address into the Download button. The manager never had to keep a page open for minutes.

What Are the Design Trade-offs?

The pattern solves the waiting problem, but it adds parts that need careful design. Four areas need decisions before you build it.

  • Request IDs and repeats

    Every submission should carry an ID, so the server can tell a repeat from a brand-new job. The goal is that repeating a request does no harm.

  • How long results stay

    Finished files and status records take storage. The team must choose how long to keep them, then tell clients the window.

  • Failures and expired jobs

    A failed job needs a stored, structured error. An expired job needs a clear answer, not a blank page or a spinner that never stops.

  • Extra complexity

    You now run a job store, background workers, status checks, and cleanup. That is more to build, test and watch than one synchronous call.

Request IDs and Safe Repeats

A client can lose the 202 reply and send the request again. The server cannot always tell a lost reply from a request it never received. So the client should send the same request ID on each attempt, and the server should return the existing job when it sees an ID it already knows. This idea is called idempotency. A separate lesson covers it in depth.

Keeping Results and Handling Expired Jobs

Decide the retention window before launch. When a job expires, its status address should say so plainly and tell the user to run the job again. A status answer should also carry a last-updated time, so stalled jobs stand out. Simply returning a 404 from the job's result URL can be unclear, because a wrong ID also returns 404. A dedicated status endpoint that answers with a clear body avoids that confusion.

Tip

Save the final status and the result together. If a worker crashes between two separate writes, the client may see pending forever even though the file exists.

When Not to Use It

Most calls should stay synchronous. Most API calls finish quickly and can return their answer over the same connection. Use this pattern only when the work is long enough to hurt the user or the server.

  • Quick lookups

    Reading a profile or a price takes little time. A job system there only adds steps and new ways to fail.

  • Need the answer now

    If the next screen cannot show anything without the result, you still have to wait. A redesigned screen with a loading state may be the better fix.

  • Clients that cannot poll

    Some older or simple clients do not handle 202 replies or follow links. In that case, put a front layer in place that hides the job steps from them.

Also weigh the running cost. Each job needs storage, a status address, a cleanup plan, and tests for every state. If the work usually finishes in a second, a plain call is simpler and easier to trust.

Check Your Understanding

Try these three short scenarios. Each one needs the ideas from this lesson to answer.

Quick check

A video site lets users convert a 2 GB file to a new format. The convert call often times out after 30 seconds. Which first reply best fixes this?

Quick check

A phone app sends a conversion request, then loses signal before it reads the 202 reply. It sends the same request again. What should the server do so it does not start a second conversion?

Quick check

A user's app polls the status address for a report that finished two weeks ago. The team deletes finished jobs after a short retention window. The app gets a clear 'expired' answer. What should the app show?

Key Takeaways

Async Request Reply splits a slow job into two calls. The first call accepts the job and returns 202 Accepted with a status address. The second part lets the client check that address, often by polling, until the result is ready. This keeps users and servers from waiting on one open connection. The price is more design work: request IDs, result retention, clear error states, and cleanup of old jobs.

Tip

Ask one question before you use this pattern: can the user do something useful while the work runs? If the answer is yes, and the work takes long enough to matter, the pattern is likely a good fit.

Sources

How is this lesson?

Last updated on 18 November 2026

Learn with me

Every lesson is free. I add new ones as I learn. Have a question, or want help with your own work? Book a short call.