Resources · 107
Asynchronous API jobs: track status, resume and cancel
Separate accepted requests, started processing and final outcomes of long-running operations.
· 3 min
What this guide helps achieve
- Define states
- Protect tracking
- Bound status queries
- Test concurrent cancellation
- Handle abandoned work
- Define repeat and expiry contracts
Quick check
- Does 202 mean the job is finished?
- Does cancellation erase every effect?
- Should status queries continue indefinitely?
Step-by-step method
- 01
Define states
Describe received, queued, active, completed, failed and cancellation requested. A 202 response does not prove success; define how the client obtains the final outcome.
Deliverable: transitions and authoritative outcome.
- 02
Protect tracking
Associate each identifier with account and request scope. Check rights for status, results and cancellation; an unguessable identifier does not replace authorisation.
Deliverable: cross-account tests.
- 03
Bound status queries
Set polling frequency and duration, terminal state and result expiry. Preserve a reference allowing resumption after browser closure without restarting processing.
Deliverable: tracking and resumption policy.
- 04
Test concurrent cancellation
Simulate cancellation while queued, running and publishing results. Define what can still be stopped and which effects remain; confirm an actually observed outcome.
Deliverable: race conditions and remaining effects.
- 05
Handle abandoned work
Identify stalled jobs, repeated errors and expired results. Assign recovery, closure or review; do not present estimated progress as proof of completion.
Deliverable: orphan-job monitoring.
- 06
Define repeat and expiry contracts
Decide whether another submission can recover the existing job. If a repeat key is used, define its account scope, lifetime, associated parameters and conflict behavior. Test acceptance with a lost response. Separate status expiry from result deletion: an unavailable result does not prove that processing never happened.
Deliverable: repeat, expiry and incident-follow-up contract.
Choose next steps using confirmed state
Check the observed state before choosing next steps.
Queued or active
Resume tracking with the same reference.
Cancellation requested
Check outcome and effects already produced.
Terminal state
Check result, rights and retention period.
Prepare recovery without inventing success
Fictional cases to adapt to your service contract. Expected results are acceptance criteria to test, not customer outcomes.
| Situation | Action to prepare | Expected evidence |
|---|---|---|
| The acceptance response is lost | Recover the job through the documented repeat mechanism or check the request before creating another. | Retained identifier, contract scope and job count in the test. |
| The client stops polling at its maximum duration | Retain a tracking-interrupted state and a recovery path; do not announce business failure without evidence. | Server state distinct from client timeout and recovery using the same reference. |
| Cancellation arrives while the result is being published | Confirm the observed outcome and reconcile effects; requesting a stop is not erasure. | Timeline, final state and proportionate list of remaining effects. |
| The result expires before the person returns | Explain expiry and apply the authorized recovery or new-request rule. | Documented retention, denied out-of-scope access and no silent restart. |
Reusable worksheet
Complete with your authorised observations. These fields are a working template, not observed results.
| Field | Information to record |
|---|---|
| Reference | Account, operation and identifier |
| State | Transition, time and source |
| Outcome | Result, error or remaining effects |
| Acceptance | Same job recovered, rights checked and outcome or uncertainty explained |
Worked example
Illustrative situation
Illustrative case: an export is accepted and the browser closes. A later session finds the ongoing job.
Decision and expected evidence
Reuse the identifier, verify result access rights and offer cancellation with confirmed status.
Distinguish the mechanisms
| Mechanism | Purpose | Check or limitation |
|---|---|---|
| Accepted | Request received for processing | Not final success |
| Cancellation requested | Intention to stop | Confirm actual outcome |
| Completed | Result available | Check rights and retention |
Management indicators
| Indicator | What it measures | First action |
|---|---|---|
| Orphan jobs | Jobs without qualified progress | Assign recovery or closure |
| Resumption | Cases resumed without duplication | Correct unnecessary restarts |
Common pitfalls
- Present acceptance as final success
- Authorise results using only a job identifier
- Poll without bounded frequency or duration
Frequently asked questions
Does 202 mean the job is finished?
No. Processing is not necessarily complete. The client needs access to an authoritative outcome.
Does cancellation erase every effect?
Not always. Some effects may already exist; specify them and how they are reconciled.
Should status queries continue indefinitely?
No. Define an appropriate frequency and duration, use the delay indication provided by the service and stop at a terminal outcome. A client-side timeout does not turn an active job into server-side failure.
Official references
References consulted: . The method and worksheet propose checks to adapt to your context; they do not constitute certification.
Continue exploring
Related analysis
