Long-running API jobs: return 202 Accepted and a status link
Short answer: If an API request that builds a report, imports a large file or generates hundreds of invoices keeps timing out, don't make the client wait. Accept the request, put the work on a background queue, and reply straight away with 202 Accepted and the address of a status resource, usually in a Location header. The client checks that address, or receives a webhook, until the job reports done and links to the result. HTTP's own specification describes 202 for exactly this kind of deferred processing.
Why long requests fail
Every layer between the client and your code has a time limit: the browser or mobile app, the CDN, the load balancer, the web server, the application server and serverless platforms. A request that takes several minutes will hit one of them, even if your code would eventually finish. The client sees a timeout error and often retries, which starts the same heavy job again and makes things worse.
Typical candidates in business apps:
- Exporting a year of orders or bookings to a file.
- Importing a supplier price list or a large customer upload.
- Generating many PDFs, such as month-end statements.
- Calling slow third-party services, like shipping-label creation in bulk.
- Rebuilding search indexes or recalculating loyalty points.
What 202 Accepted means
RFC 9110, the HTTP semantics specification, says a 202 status means the request has been accepted for processing but the processing hasn't been completed, and might or might not eventually be acted upon. It's intentionally noncommittal: its purpose is to let a server accept a request for some other process, perhaps a batch that runs later, without requiring the client's connection to stay open until it's finished. The specification also notes that HTTP has no way to re-send a status code from an asynchronous operation, so the response should describe the request's current status and point to a status monitor.
That last point is the design: the 202 response tells the client where to look next.
The pattern step by step
- Client sends the request, for example
POST /exportswith the date range. - Server validates it quickly, creates a job record with a unique ID and the status "queued", and puts the job on a background queue.
- Server replies at once with
202 Accepted, aLocationheader such as/exports/jobs/8f3c, and a small body containing the job ID and status. - A background worker picks up the job, updates its status to "running", and records progress if that's useful.
- Client polls the status URL. While the job runs, it returns "queued" or "running", optionally with a
Retry-Afterheader suggesting when to check again. - When finished, the status shows "succeeded" with a link to the result, such as a download URL, or "failed" with a clear error message.
If clients have their own servers, offer a webhook callback as well, so they don't need to poll.
Designing the status resource
Keep it simple and predictable:
- Fields: job ID, status, created and updated times, progress if known, a result link when done, and an error object when failed.
- Stable statuses: a short list such as queued, running, succeeded, failed and cancelled. Document them.
- Access control: only the account that created the job can see it.
- Retention: keep finished jobs and their results for a stated period, then delete them.
- Cancellation: for long jobs, a
DELETEor cancel action is often worth adding.
Avoiding duplicate jobs
Clients retry. Networks drop responses. Without protection, a client that didn't receive your 202 may submit the same export again and again. Accept an idempotency key header on job-creating requests, store it with the job, and return the existing job for a repeated key instead of creating a new one.
Polling politely
Tell clients how often to check, using Retry-After on status responses, and back off as jobs take longer. On your side, make status checks cheap: read one small row, don't recalculate anything. Rate-limit aggressive polling per key.
Using it in your own front end
The same pattern works inside your own web app. The browser submits the export, receives the job ID, shows "Preparing your file…" with progress, polls quietly, then offers the download or sends an email with a link. Users can keep working, and closing the tab doesn't cancel the job.
Telling users what's happening
For people waiting on the result, a little honesty goes a long way. Show that the job has started, an approximate stage such as "collecting records" or "building file", and what will happen when it's done: a download button, an email or both. If a job fails, say so plainly with a way to try again, rather than leaving a spinner running forever.
When not to use it
For work that finishes quickly and reliably, a normal synchronous response is simpler. Reach for 202 when work regularly runs longer than your timeouts allow, is heavy enough to compete with normal traffic, or depends on slow external services.
A worked example
Picture a hypothetical Minneapolis cleaning-services company whose admin panel offered a "download all jobs for the year" export. As the business grew, the export hit the load balancer's timeout and staff clicked it again and again, slowing the whole app. The developer moved the export to a background worker, changed the endpoint to return 202 with a status link, added an idempotency key from the button, and had the page poll for completion and show a download link. Exports now finish reliably, and repeated clicks reuse the same job.
FAQ
Should the status endpoint return 200 or 202 while running?
Many APIs return 200 with the current status in the body. Document your choice and be consistent.
Can the status URL redirect to the result?
Some APIs return a 303 See Other pointing to the finished result. A result link in the body is simpler for most clients.
What if the job fails halfway?
Record the failure with a useful message, and make retries safe by designing the job to resume or restart cleanly.
Do I need a separate queue system?
Not necessarily. Many frameworks include a background job feature backed by your database or a cache.
If parts of your app time out on big tasks, tell us which ones and we'll help move them to background jobs.