# 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.

From "System design", a free course by Venkat R. Murty: https://designervenkat.online/learn/system-design/async-request-reply

## 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.

- **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. **Send the request:** The client calls the API once with the job details, such as the date range and the file format.
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. **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. **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.

```
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. **Click:** The dashboard sends one POST request to the export API with the date range and the CSV format.
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. **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. **Poll:** The dashboard checks the status address at a set interval. Each answer says running, and the progress number moves upward.
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. **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:

```text
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?

A. Keep the connection open longer and raise the timeout to ten minutes.
B. Return 202 Accepted with a Location header to a status address, and convert the file in the background.
C. Return 200 OK only after the conversion finishes, and ask the user to upload again if it fails.
D. Return 500 Internal Server Error so the app shows an error and the user tries again later.

**Answer:** B. A 202 with a status address lets the server reply at once while the conversion runs. The other options still hold the connection open or report failure, so the user still waits or gets an error.

**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?

A. Start a second conversion, because the first reply was lost.
B. Reject the repeat with 400 Bad Request and delete the earlier job.
C. Read a request ID the app sends with every attempt, and return the existing job when that ID is already known.
D. Wait for the app to poll, then count both jobs and bill for each one.

**Answer:** C. The server cannot tell a lost reply from a request it never got. A request ID lets it recognize the repeat and return the job it already started, so the repeat does no extra work.

**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?

A. A message that the report has expired and an offer to run the export again.
B. A message that the job is still running, and a faster polling loop.
C. The same blank report page, since status answers always return a file.
D. A message that the server crashed, so the user must pay for a new export.

**Answer:** A. Expired results are removed under the retention policy, so the app should say so plainly and offer a new run. Polling faster cannot bring back deleted data, and a crash message would be false.

## 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

- [Asynchronous Request-Reply pattern, Azure Architecture Center (Microsoft Learn)](https://learn.microsoft.com/en-us/azure/architecture/patterns/asynchronous-request-reply)
- [RFC 9110, HTTP Semantics (IETF), section 15.3.3 on 202 Accepted](https://httpwg.org/specs/rfc9110.html)
- [202 Accepted, HTTP status code explained (http.dev)](https://http.dev/202)
- [202 Accepted: HTTP Status Code Meaning, Causes, and Fixes (terminalfeed.io)](https://terminalfeed.io/http/202)
- [Async API Job Status Endpoint Example and Best Practices (ammune.ai)](https://ammune.ai/blog/async-api-job-status-endpoint-example)
- [Long-Running Operations in ASP.NET Core APIs: Enterprise Decision Guide (codingdroplets.com)](https://codingdroplets.com/long-running-operations-aspnet-core-enterprise-guide)
- [Long-Running Operations in REST: How It Works (adhdecode.com)](https://adhdecode.com/api-architecture/rest-api-design/long-running-operations-rest/)
- [Webhook vs. API Polling in System Design (GeeksforGeeks)](https://www.geeksforgeeks.org/system-design/webhook-vs-api-polling-in-system-design/)
