How to Return HTTP 202 Accepted and Let API Clients Check Job Status

When an API request starts work that will outlast the request, the server can return 202 Accepted and give the client a URL for checking the job's status. HTTP 202 means the server accepted the request for processing, but the work may not have started or finished. The client needs another way to check the outcome because the server cannot send a later response to the original request.

A job is a record of background work, such as generating a file or processing a large data set. The server returns a reference to the job and updates its status as the work progresses. The client can then handle success or failure without keeping the original connection open.

Return a job reference with 202

Use 202 Accepted when the server accepts a request that it will process later. Return 200 OK when the request has already been processed successfully and the response contains its result. The HTTP status definition calls 202 noncommittal, meaning acceptance does not guarantee that the job will succeed.

Include a job ID or status URL in the response body so the client knows where to check. For example:

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "jobId": "<job-id>",
  "status": "accepted",
  "statusUrl": "/jobs/<job-id>"
}

The server fills in these placeholders when it handles the request. A client can save the statusUrl and use it to check the job later. The Canva design-generation API follows this general pattern: the client creates a job, then checks a separate endpoint for its status and result.

Let clients check progress and results

Create a status endpoint, a URL clients can request to see a job's current state. For example, GET /jobs/<job-id> could return:

{
  "jobId": "<job-id>",
  "status": "running"
}

When the job finishes, the endpoint can report success and provide the result or a URL where the client can retrieve it. If the job fails, return a failure state and enough information for the client to understand what happened. Choose status names and response fields that fit the API, and document what each state means.

The client polls this endpoint by sending repeated requests until it sees a final state, such as success or failure. The polling model gives clients direct control over when they check. Avoid having clients poll continuously: polling traffic grows as the number of clients and how often they check increase, even when few jobs change state.

For clients that can expose a public endpoint, a webhook offers another option. With a webhook, the server calls a client-provided URL when a job changes state or finishes. Browsers and mobile apps generally cannot expose such an endpoint, so polling remains a better fit for those clients.

Keep accepted jobs recoverable

Create and store the job record before returning 202. Then give a background worker, a separate process that performs tasks outside the original request, access to the work. If the server tells the client that a job exists but loses the job before a worker processes it, the status endpoint cannot give the client a reliable outcome.

Have the worker update the stored job state as it runs. Record failures as well as successes so the status endpoint does not leave clients waiting indefinitely after an error. The job-resource design example illustrates this approach with a job record whose status changes as background work proceeds.

Protect status requests with the same access rules you use for the related data. A job ID should not, by itself, grant access to another user’s job or its result. Also define how long the server keeps job records and what the status endpoint returns after a record expires. This tells clients whether the job failed or the record is no longer available.

What I'm building

Delegate tasks. Get software.

Give Vroni a GitHub issue, bug report, spec, or rough idea. It reads the repo, plans the change, writes code, runs checks, and works toward a review-ready pull request.

Take a look at vroni.com