Skip to content
System Design Lab
Microservice Patterns

Asynchronous Request-Reply

For work that takes seconds or minutes, answer at once with 202 Accepted and a status URL, do the work in the background, and let the client poll or be notified — instead of holding a connection open until something times out.

Intermediate 4 min read· Updated 2026-11-18

What you will learn

  • Explain why long synchronous requests fail behind proxies and exhaust threads.
  • Implement 202 Accepted, a status endpoint and a result location.
  • Choose a polling interval or a push notification.
  • Handle retries and duplicate submissions safely.

Before you start

Overview

When you drop a suit at the dry cleaner, you do not wait at the counter for two days. You get a ticket, go home, and call or check online until it says "ready".

HTTP is request-response, and every hop on the way — browser, CDN, load balancer, gateway — has a timeout, often 30–60 s or less. Holding a request open for a long job also pins a server thread or connection. With asynchronous request-reply, the API validates the request, enqueues the work and returns 202 Accepted with a status URL. The client polls that URL (respecting Retry-After) or receives a callback; when done, the status points to the result.

Run it

Users start report exports that take 4–8 s, behind a proxy that cuts connections after 10 s. Compare failures and API thread use in A, then the number of Status polls in B and C.

Loading simulation…

The flow

  1. POST /exports → validate, store a job, enqueue → 202 Accepted, Location: /exports/42/status, Retry-After: 2.
  2. GET /exports/42/status → 200 {"status":"running"} while in progress.
  3. When finished → 303 See Other, Location: /exports/42/file (or 200 with a result link); on failure, a status with the error.
  4. The client downloads the result; the job record expires after a retention period.

Implementation

Spring: accept, process in the background, report status
@PostMapping("/exports")
ResponseEntity<Void> start(@RequestBody ExportRequest req, @RequestHeader("Idempotency-Key") String key) {
    Job job = jobs.findByKey(key).orElseGet(() -> jobs.create(key, req));   // same key → same job
    queue.send("exports", job.id());
    return ResponseEntity.accepted()
        .location(URI.create("/exports/" + job.id() + "/status"))
        .header(HttpHeaders.RETRY_AFTER, "2").build();
}

@GetMapping("/exports/{id}/status")
ResponseEntity<JobStatus> status(@PathVariable String id) {
    Job job = jobs.get(id);
    if (job.isDone()) return ResponseEntity.status(HttpStatus.SEE_OTHER).location(URI.create("/exports/" + id + "/file")).build();
    return ResponseEntity.ok().header(HttpHeaders.RETRY_AFTER, "2").body(job.status());
}

Trade-offs

BenefitsCosts
ReliabilityNo proxy timeouts, no threads held; work survives client disconnects.Job state must be stored and expired; more endpoints to secure.
LatencyThe API answers in milliseconds.Results are noticed up to one poll interval late.
Client effortStandard HTTP semantics.Clients must implement polling or callbacks and handle failures.

Production considerations

  • Require an Idempotency-Key so a retried POST does not start a second job.
  • Authorise status and result URLs: job ids must not be guessable or shareable by accident.
  • Put the work on a durable queue (queue-based load leveling), not an in-memory executor.
  • Return Retry-After and rate-limit status endpoints to keep polling cheap.

Further reading

Related topics