2026-09-27 · 8 min read
- http
- async
- reliability
HTTP 202 Accepted lets a server acknowledge a request before processing reaches a final outcome. The original response cannot later change, so the application protocol must define how clients observe progress, retrieve results, handle failure, and stop waiting.
Use asynchronous acceptance when work genuinely outlives a practical request deadline. It should not hide overload, silently discard requests, or turn validation errors that are already known into an opaque background failure.
Commit job creation before responding
Validate authentication, authorization, syntax, and immediately knowable preconditions first. Persist the job and its initial state durably before returning 202, then enqueue work through a transactionally safe mechanism such as an outbox.
- Return a stable opaque job identifier.
- Provide a documented status resource.
- Record submission time and retention limits.
- Never acknowledge work that exists only in memory.
Make submission idempotent
A client can lose the 202 response after the server creates the job. Accept a scoped idempotency key or another stable operation identity, store the normalized request and outcome atomically, and return the existing job for an equivalent retry.
Define key scope, request comparison, expiry, conflict behavior, and tenant isolation. Do not let one user's key reveal another user's job or permit a changed payload to inherit an unrelated result.
Design the status state machine
Publish a small state vocabulary such as queued, running, succeeded, failed, and cancelled, with explicit terminal states. Include safe timestamps, progress only when meaningful, typed terminal errors, and a result link or representation after success.
Authorize every status, result, and cancellation request. Use unguessable identifiers as defense in depth, not as the authorization mechanism, and prevent shared caches from exposing user-specific job state.
Bound polling, cancellation, and retention
Provide Retry-After where appropriate or document a polling interval. Clients should add jitter, back off within a maximum delay, honor an overall deadline, and stop at a terminal state. Servers need per-principal limits and efficient conditional responses.
Define whether cancellation is requested or guaranteed, how races with completion resolve, and what state remains visible. Retain terminal metadata long enough for realistic clients, then expire results and status records under a documented policy.
Rehearse every ambiguous boundary
Use Flashman's URL parser for status links, JSON formatter for state payloads, timestamp converter for polling windows, UUID generator for synthetic job IDs, and cron helper for retention cleanup schedules.
Test lost submission responses, duplicate keys, changed payloads, enqueue failure, worker crash, retries after side effects, completion during cancellation, authorization revocation, polling bursts, service restart, expired status, result cleanup, and accessible terminal errors.