Async jobs: say queued, running, cancelled, or unknown

A model to inspect

Long-running work

01Accept job
02Expose status
03Run or cancel
04Set terminal state

Cancellation is only terminal after the defined boundary.

Original conceptual diagram · not a live trace or measured result.

Design the status vocabulary first

Before a worker exists, define what each visible state means. queued means accepted but not started; running means a worker has begun; succeeded means the declared result is available; failed means it stopped with a user-safe reason; cancel_requested means the request was recorded but not yet confirmed; cancelled means the cancellation boundary was reached. Reserve unknown for loss of evidence, not ordinary delay.

HTTP 202 is deliberately noncommittal: it says a request was accepted for processing, not that processing finished. That makes it a useful guardrail for conversational copy. “Your request is queued; you can check its status” is more useful and more accurate than “done” when the service only accepted a message.

Give the job an inspectable home

Return a job ID, status URL or in-product status view, submitted time, and the next safe action. The status endpoint should show only the information the caller is authorized to see: state, meaningful phase, user-safe error, result reference where available, and cancellation availability. Avoid progress bars with invented precision. If a provider gives no reliable percentage, show “processing” and the last verified event instead.

Google’s long-running-operation guidance models a resource that can be polled until done. Use that pattern as an architectural reference, not an instruction to poll aggressively. Let the client back off, push an update where appropriate, and preserve the job identity across a conversation restart.

Choose a cancellation boundary

Cancellation means different things at different stages. Before a worker claims the job, it may remove it from the queue. During local computation, the worker may stop at a checked safe point. After a downstream booking or email has been committed, it may only begin a separate compensating process. State the boundary in the job contract and user language. “Cancellation requested” is honest while the worker has not confirmed it.

Counterexample: a job that creates a supplier order calls the supplier, then the user presses cancel. Marking it cancelled merely because the UI button returned is a false claim. Keep it running or unknown while looking up the external reference; if cancellation is impossible, explain the next review path.

Make side effects resumable

Store the job input snapshot, authorization scope, worker attempt count, event timestamps, and external references. A restarted worker should be able to decide whether to resume a phase, verify an earlier call, or stop because cancellation won. Do not reconstruct the input solely from raw conversation history; fields may have been corrected after submission. A job snapshot is not permission to retain everything forever, so apply retention and access rules deliberately.

For a hypothetical image-analysis request, freeze the exact uploaded file reference and policy version, not a copy of every prior chat message. If the file is revoked before work begins, fail safely. If a result exists but access was later removed, the status record can say it is no longer available without leaking the result.

Wire status language to real events

Map worker events to the state machine in one place. The conversation layer should consume that mapping rather than inventing its own phrases. Distinguish transient retrying from a permanently failed job, and distinguish a lost notification from lost work. An operator view may include trace IDs and retry reasons; the user view should expose the actual decision and a next step.

Set success criteria that are reviewable: every accepted job gets an ID; every terminal state has a recorded transition; cancelled is emitted only after its boundary; and an unavailable status service does not masquerade as success. A conceptual state diagram is a communication aid, not evidence that each worker conforms.

Exercise the uncomfortable paths

Test queue delay, worker crash after claiming, external timeout, duplicate delivery, cancellation before start, cancellation during work, cancellation after external commit, and status read after authorization revocation. Review one trace from each path with service owners. The important question is not whether the spinner continued; it is whether the caller was told only what the system could establish.

The limitation is unavoidable: some external systems cannot prove an outcome promptly. A well-designed service makes that uncertainty visible and assigns it to reconciliation. It does not erase it with optimistic wording.

Take it into the review

Job-state acceptance checklist

State	Verified meaning	User action	Owner
queued	stored; no worker claim	view status; cancel	queue
running	worker has a lease	view status; request cancel	worker
cancel_requested	request stored	wait for outcome	worker
succeeded	declared result persisted	open result	result service
unknown	outcome not established	request support	reconciliation

A starting artifact to adapt to your service—not a ready-made policy, compliance certificate or test result.

Primary reading

Sources and limits

These links support the architecture, policy, or product behavior discussed above. Vendor documentation describes vendor features; it is not independent proof of performance. Current details should be rechecked before a production decision.

What the sources establish

RFC 9110 section 15.3.3: 202 Accepted

HTTP 202 indicates acceptance for processing while deliberately not committing that processing has completed.

Limits: HTTP does not define an application job-state vocabulary or cancellation policy.

Checked 2026-09-19 · RFC Editor · source publication date not established.

Open original source ↗

AIP-151: Long-running operations

AIP-151 documents a long-running operation resource that callers can inspect until completion.

Limits: This is Google API design guidance, not evidence that another provider exposes equivalent status or cancellation behavior.

Checked 2026-09-19 · Google API Improvement Proposals · source publication date not established.

Open original source ↗

Procedures and worked examples are editorial synthesis. Preparation/review dates are not claimed historical publication dates.