The Async Job Pattern

Long-Running Operations: 202 and the Job Resource made the case that holding a connection open for 15 minutes bets against every timeout in the chain. The escape is to change what the request *means*: POST /reports no longer means "produce the report", it means "create a job that will produce the report". The server validates, persists a job row, enqueues it, and returns 202 Accepted with the job's id and a Location — in milliseconds, regardless of how long the work takes. Everything after that is a conversation about the job resource.

That shift moves the hard parts into the contract, where they belong. The job needs an id the client can store. It needs a status drawn from a documented set. It needs a place to put the result (inline for small results, a URL for large ones), a place to put the error when it fails, and an answer to "how long will this resource exist". Skip any of these and the client invents the answer: polls forever, assumes failed is final when it was a transient retry, or stores a result URL that 404s next week.

The worker side is architecture (Background Jobs and Workers, Message Queues — the queue, the retry policy, the visibility timeout); the API side is the contract that hides all of that behind a resource whose behavior is stable across implementations. A client should never learn which queue technology is behind /jobs/{id}.

Five states cover almost every job: queued (accepted, not started), running (a worker owns it), succeeded, failed, cancelled. Three are terminal; the contract says which, because "terminal" is what tells a client to stop polling. Transitions are explicit: queued → running → succeeded|failed, queued|running → cancelled, and — the one most contracts forget — whether failed can go back to queued on an automatic retry. If the worker retries transient failures internally, the client should see running with an attempt counter, not a failed that later flips back; a state that un-terminates is a state machine that lied (see Resources Have State Machines).

Progress is a field, not a state: progress: { "done": 4200, "total": 10000, "message": "rendering pages" }, updated at a documented cadence and explicitly *advisory* — the client may render it, may not branch on it. Cancellation is a request, not a command: POST /jobs/{id}/cancel moves the job to cancelling (or records a cancel flag) and the worker acknowledges at its next checkpoint; the contract states that a job may still complete after a cancel was accepted, and what the client sees then. A cancelled state that the server cannot actually guarantee is a promise the contract should not make.

Results and errors are typed. Small results inline (result: {…}), large ones as a URL with an expiry, errors as the same The Error Model: Structure Over Apology the synchronous API uses — code, message, retryable — so a client's failure handling does not fork for async operations. Retention is a number: "job resources and results are readable for 7 days after reaching a terminal state; afterwards GET returns 404 with code JOB_EXPIRED". Consumers plan storage and reconciliation around that number; without it they plan around a guess.

Job creation is a non-idempotent POST with a side effect that costs money or time, so it is exactly the case Idempotency Keys: The Mechanism exists for: the client sends Idempotency-Key, a retried create returns the *same* job with 200 instead of a second 202, and the key is scoped to the caller and expires after the retention window. Without this, a timeout on the create — the most common failure, because clients wait for a 202 they expect to be instant — spawns a duplicate job, a duplicate report, and a duplicate invoice line for the compute.

Learning that a job finished is its own contract (How the Client Learns the Job Finished): polling with Retry-After and backoff as the always-available baseline, a webhook for servers, SSE on /jobs/{id}/events for browsers and agents that want the progress stream. The job resource stays the source of truth whichever channel delivered the news — a client that receives a "succeeded" webhook still fetches the job to get the result, so a duplicated or reordered notification cannot mislead it.

Listing jobs (GET /jobs?status=running&kind=report.generate) turns the pattern into an operational surface: consumers reconcile what they started against what exists, operators see the backlog. It is a collection, so it is bounded and cursor-paged (Unbounded Collections: The Anti-Pattern With a Fuse) and filterable on the fields the state machine defines.