Long-running operations: 202 Accepted and a status resource

What it is

RFC 9110 (cited) defines 202 (Accepted) as intentionally noncommittal: the request has been accepted for processing but processing has not completed, it might still be refused later, and HTTP has no facility for re-sending a status code from an asynchronous operation. The representation sent with a 202 ought to describe the request's current status and point to (or embed) a status monitor. Google's AIP-151 (cited) makes that monitor a first-class resource: methods that may take a significant amount of time return an Operation with a name, a done flag, metadata for progress and partial failures, and on completion either error or response. Its rule of thumb is that work over about 10 seconds warrants the pattern and that operations may expire, with 30 days suggested.

Why it matters

Blocking a connection for minutes fails at every layer: proxies cut idle connections, clients time out and retry, and a retried non-idempotent job runs twice. An explicit operation resource lets the client disconnect, poll and recover after its own restart, and gives the server one place to record the outcome.

How to apply

• Return 202 Accepted with a Location (or body link) to /operations/{id} and include the operation representation in the body, so the client needs no immediate second request.
• Model the operation with done, metadata (progress, counts, non-fatal errors) and exactly one of error or response once done; use the same error shape as synchronous failures.
• Accept a client-supplied idempotency key on the starting request, so a retry after a lost 202 returns the same operation instead of starting a second one.
• Support polling with Retry-After hints; offer a webhook for clients that can receive one, but keep polling as the fallback.
• Document expiry: how long the result stays retrievable and what a GET on an expired operation returns.
• For resources created asynchronously, let List and Get show the resource with a state that marks it as not yet usable (AIP-151).
• Decide how parallel operations on one resource behave: queue them, or reject with a conflict error naming the running operation.

Pitfalls

Returning 202 and then processing synchronously anyway. Changing the result type of an existing operation, which AIP-151 lists as a breaking change. Using 200 with a "pending" body, which makes caches and clients treat the job as finished. Losing operation records on restart, so the client can never learn the outcome. Polling endpoints without rate limits.

Answering synchronously when the work is fast

Decide per request, not per operation type, when latency is bimodal. Run the job for a bounded time and, if it completes, answer 200 or 201 with the result; otherwise answer 202 with the operation resource. RFC 7240 gives the client a say: Prefer: wait=N bounds how long it will wait, Prefer: respond-async asks for the 202 path outright, and the server reports what it honoured in Preference-Applied. Document both response shapes for the operation and let the SDK's wait helper normalise them, so callers see one result type. Reserve the always-202 design for work that is always long.