When you design the status-polling endpoint for an async request-reply API — the resource a client hits after receiving HTTP 202 — what should it return across the job's lifecycle, from just-submitted to complete, in terms of status codes, body shape, and headers?

## Treat job progress as a state machine Designing the status resource well means treating job progress as an explicit **state machine** and mapping each state onto a concrete HTTP response shape, rather than leaving the client to guess. A typical state machine has at minimum `pending`, `running`, `completed`, and `failed`, and the status body should carry this as an explicit field (e.g. `{"status": "running"}`) rather than relying purely on HTTP status codes, since a `GET` against an existing, valid resource is naturally still `200 OK` in most states — the distinguishing information belongs in the body, not the transport-level code. ## While the job is in flight - **`Retry-After`.** While the job is in flight, the response can include a `Retry-After` header (either a fixed number of seconds, or a smarter estimate based on the actual work remaining) so well-behaved clients know when to check again instead of guessing an interval. - **Cache headers.** The response must also be marked non-cacheable — `Cache-Control: no-store`, or `no-cache` with `must-revalidate` — because a stable URL with a volatile body is exactly the case reverse proxies and CDNs get wrong by default, silently serving a client an old 'running' response long after the job actually finished. ## Two shapes for a terminal state Once the job reaches a terminal state, the design has two common shapes. 1. The first embeds the result directly in the status body, which keeps the client model simple: one `GET`, one response shape, whether pending or done. This works well when the result is small, like a JSON summary or a handful of fields. 2. The second returns `303 See Other` with a `Location` header pointing at a separate result resource, decoupling the lifecycle and access rules of the result (which might be a large file, have its own cache headers, or need independent sharing) from the lifecycle of the job-status record itself. Failure should also be represented explicitly, typically `{"status": "failed", "error": {...}}` with enough detail for the client to decide whether to retry the original submission or give up, while the HTTP status of the status `GET` itself usually stays 200, since the poll succeeded even though the underlying job did not. ## What happens to the record afterwards A subtler but important design point is what happens after the client is done with the record. Job-status entries must not live forever: without a TTL or a scheduled cleanup job, a busy API accumulates unbounded storage for jobs nobody will ever query again. Production designs commonly: - expire records some window after completion, often 24 to 72 hours - sometimes exposing an explicit `DELETE` on the job resource so clients or operators can clean up proactively This matters operationally because the job store is now a piece of durable state the team owns and must monitor, unlike a purely synchronous endpoint whose only state is the in-flight HTTP call. ## Why polling is a sound design `GET` on the status resource is inherently **safe and idempotent** — issuing it any number of times has no side effects and always reflects current truth — which is exactly why polling is a sound design: clients can poll freely without coordination concerns, unlike retrying a `POST`. A concrete real-world example is GitHub's asynchronous migration/export APIs, which accept a request to generate a repository export, return 202 with a status URL, and require the client to poll that URL until it reports the export is ready, at which point it supplies a download link separate from the status resource itself — exactly the redirect-to-result-resource shape described above.