HTTP 202 Accepted indicates that a request was accepted for processing but that processing has not completed. It is useful for asynchronous workflows such as exports and long-running analysis. It does not guarantee the work will succeed, and the original HTTP exchange does not automatically deliver a later final result.
A reliable API defines how clients discover progress and completion after that first response. This guide explains durable identity, status resources, polling, and failure so acceptance is not confused with a completed business action.
Define what accepted actually means
State the server’s acceptance boundary. Does it mean validation passed and a durable work record exists, or only that an in-memory attempt was started? The latter may not satisfy the client’s reliability expectation.
Reject known invalid or unauthorized requests before claiming acceptance. A deferred worker should not be the first place that basic object permission is checked if the initial endpoint can establish it correctly.
Document remaining uncertainty. Capacity, external dependencies, and later validation can still cause failure. A 202 response should not be presented in the interface as the requested export or operation already finished.
Persist an authoritative work identity
Create a durable job or operation record with a controlled identifier. Preserve its input identity, owner, and initial state according to the data policy. A worker restart should not erase the only evidence that the request was accepted.
Keep the identifier separate from authority. A random-looking job ID reduces guessing risk but does not replace authentication and ownership checks. Every later read or action still needs authorization.
Define how workers claim and finish the job. The HTTP status code does not provide exactly-once processing or exclusive ownership. Use the appropriate application transaction and idempotency design.
Return a useful monitoring contract
Provide an appropriate status URL or other documented tracking mechanism. The response should describe how the client learns the current state and where an accepted result will become available.
Keep identifiers and links scoped to the intended user and API origin. Avoid leaking internal queue names or private infrastructure endpoints. A monitor URL is part of the public contract and needs stable behavior.
Do not assume HTTP supplies a universal mandatory response-body schema for every 202 workflow. Choose and document the application’s representation, while preserving the status code’s actual meaning.
Define a small explicit state machine
Use states such as pending, running, succeeded, failed, and cancelled according to the workflow. Explain terminal versus nonterminal states and which transitions are valid. Avoid one generic complete flag that hides failure.
Record final outcome separately from transient worker attempts. A failed attempt may be retried while the accepted job remains pending. Clients need the meaningful business state, not every infrastructure restart as a new job.
Make transitions durable and consistent. A success state should not appear before the validated result is available through its authorized retrieval path.
Authorize every status and result request
Check current user, tenant, and object access on the monitoring endpoint and final result. A status resource can reveal private business activity even if it does not return the complete output.
Review access changes during long-running work. A user who submitted a job may later lose permission. Define whether processing continues and whether the result remains readable under the current policy.
Apply the same boundary to cancellation and retry endpoints. Possession of an operation URL should not grant the ability to stop another user’s work or start additional expensive attempts.
Make repeated submission predictable
Clients can lose the acceptance response after the server stored the job. Retrying the original request can create duplicate work unless the API has a deliberate submission-identity mechanism.
Use supported idempotency semantics where the business requirement needs them, and scope identity to the relevant owner and operation. Record whether the same key with different input is rejected or handled through another documented policy.
Do not conflate a job identifier with a reusable idempotency key without specifying their roles. One identifies an accepted operation; the other can reconcile repeated attempts to request it.
Bound polling and server resource use
Document a reasonable polling interval or backoff guidance. A client checking every few milliseconds can turn a long-running job into a large load on the status service.
Use appropriate retry and waiting behavior for temporary monitoring failures. A failed status request does not mean the underlying job failed. Keep those error categories distinct in the client interface.
Protect submission and status endpoints with relevant resource controls. Job count, data volume, and worker capacity may matter more than raw request count. Limit the expensive operation the API actually creates.
Specify cancellation and result retention
Cancellation can mean a request to stop work, not proof that every external effect was undone. Define the terminal cancellation state and how workers observe it. Some operations may no longer be cancellable after a publication boundary.
Give results and status records an explicit retention period or policy. An old monitor URL should have predictable expired or unavailable behavior rather than silently pointing to a reused identifier.
Keep deleted results and their backups within the approved data lifecycle. Removing a status record does not necessarily delete all generated artifacts.
Test ambiguous and interrupted outcomes
Test acceptance-response loss, worker crash, repeated submission, status-service outage, cancellation during work, and failure after an external side effect. Inspect final durable state and client behavior.
Verify that a job cannot remain running forever without an owner or recovery signal. Track backlog age and terminal outcomes, not only submission success. A high rate of 202 responses can coexist with no useful completed work.
For an export API, store the accepted request durably, return an authorized monitor URL, publish a validated file, and expose an explicit success or failure state. The initial 202 then starts a clear workflow instead of disguising uncertainty as completion.
Frequently asked questions
Does 202 guarantee the task will succeed?
No. It indicates acceptance for processing, not completed processing.
Does the original response deliver the final result later?
Not automatically. The API needs a separate tracking or delivery contract.
Where is the status meaning documented?
Read MDN’s 202 Accepted reference and define the application’s monitoring behavior explicitly.
For a complementary workflow, read Idempotency Keys: Reliable Retries for APIs.
