HTTP 202 Accepted: Give Long-Running Jobs a Status URL

Suppose your reporting API exports a large CSV. The browser gives up before the worker finishes, so the user clicks Export again. Now the server may be building two files, and the browser still has no way to tell which request worked. The API needs to tell the caller what happened before the file is ready.

Return 202 Accepted after you durably record the work, and give the caller a job ID and a status URL it can read. The initial response acknowledges acceptance. The status URL tells the caller whether the work is queued, running, successful or failed. RFC 9110 defines 202 as acceptance for processing while work remains incomplete. A status resource is a practical way to report what happens next.

Make the first response worth trusting

Validate and authorize the request before creating the job. For an export service, one option is to write a job row that workers can claim. If you also need to send to a separate broker, consider recording an outbox entry with the job in the same transaction and relaying it afterward. That gives you a way to recover when the API commits the job but the broker is unavailable. The worker still needs to tolerate duplicate deliveries. If you can’t commit the work, report the request failure instead of returning a job ID you can’t track. See AWS’s transactional outbox guidance.

HTTP/1.1 202 Accepted
Content-Type: application/json
Cache-Control: no-store

{
  "jobId": "exp_8f2",
  "state": "queued",
  "statusUrl": "/exports/exp_8f2",
  "pollAfterSeconds": 3
}

This example puts the status URL and polling hint in the body. A documented Location header is another way to advertise the status URL. The three seconds are an example, not an HTTP rule or a completion estimate. Microsoft’s asynchronous request-reply pattern shows a variant with Location and Retry-After.

Let the status URL answer a separate question

When GET /exports/exp_8f2 succeeds, return 200 OK with the current job state. In this design, a job can be failed even though the status lookup succeeded. A transient error reaching the status endpoint means the caller has no fresh information about the job. Keep those two cases separate in your client. On success, return a result reference the caller is authorized to use. On failure, return an actionable error code without internal logs or credentials.

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store

{
  "jobId": "exp_8f2",
  "state": "succeeded",
  "resultUrl": "/exports/exp_8f2/file"
}

Authorize each status and result lookup against the requesting account or tenant. An opaque job ID is useful for routing, but possession of it should not grant access. Document how long status and results are retained and what callers see after expiry. Stop polling on a terminal state. While work is pending, use a bounded interval and spread out client polls. If the endpoint returns 429 with Retry-After, respect that delay. RFC 6585 describes the 429 response.

Rehearse the case where the browser never sees the 202

Ask the client to supply a unique key for one export attempt. Scope it to the caller and persist it with the job, with a uniqueness constraint. If the same key and request arrive again, return the same job reference. Reject incompatible inputs with the same key, and document how long that protection lasts. This matters when the job exists but the connection drops before the caller reads the response. Krova’s webhook retry guide covers the related case of receiving the same event twice.

1. Drop the first response after commit. Repeat the POST with the same key and confirm there is one job ID.
2. Pause the worker and confirm the status stays queued. Force a processing failure and check that the status records the failure instead of polling forever.
3. Request the job and file as another account. Then test an expired job. Confirm both cases follow your documented contract.

If the caller can recover a job ID after a lost response and tell the difference between a failed job and an unreachable status endpoint, the export flow has a useful contract. A fast initial response is only one part of it.

This guide was prepared with AI assistance using the linked standards and documentation. The export scenario and responses are illustrative.