202
Success
202 Accepted: Handling Asynchronous Requests
✦ The Golden Answer: The 202 Accepted status code means that the server has accepted the request for processing, but the processing has not yet been completed. This is a commitment to process the request asynchronously. The client should not wait for the final result in the same connection, but can poll a status endpoint or receive a webhook callback.
When to Use 202 Accepted
- Long‑running operations – e.g., generating reports, processing large data sets, converting videos.
- Batch jobs – where the request initiates a background task.
- Email sending – the server queues the email and returns immediately.
- Webhooks – the request triggers an action that will later call a callback URL.
Response Body and Headers
While 202 does not require a body, it's common to include:
- Location – a URL where the client can check the status of the request (e.g.,
/api/status/123). - Retry-After – suggested time in seconds after which the client should check again.
- JSON body – containing a job ID, status URL, or an estimated completion time.
HTTP/1.1 202 Accepted
Location: /api/status/abc-123
Retry-After: 30
Content-Type: application/json
{"job_id":"abc-123", "status":"processing", "estimated_seconds":30}
Client Implementation
The client should:
- Receive the 202 response and extract the
Locationheader or job ID. - Poll the status endpoint periodically (respecting
Retry-Afterif provided). - When the status endpoint returns 200 or 201, the job is complete.
- If the job fails, the status endpoint may return 500 or another error code.
Example Flow
| Step | Direction | HTTP Message |
|---|---|---|
| 1 | Client → Server | POST /api/report HTTP/1.1 |
| 2 | Server → Client | HTTP/1.1 202 Accepted |
| 3 | Client → Server (polling) | GET /api/status/456 HTTP/1.1 |
| 4 | Server → Client | HTTP/1.1 200 OK |
Best Practices
- Always provide a way to check status – use
Locationor include a job ID in the body. - Set realistic Retry-After – avoid client hammering your server.
- Handle failure gracefully – if the job fails, the status endpoint should return an appropriate error code and message.
- Idempotency – if the same request is submitted twice, avoid duplicating work (use a unique idempotency key).
Frequently Asked Questions
Is 202 Accepted considered a final response?
No, it's a provisional acceptance. The client must not assume the request has been fully processed. It should check the status endpoint for the final outcome.
What if the client can't poll?
You can provide a webhook callback: the client provides a callback_url in the request, and the server sends the final result there. 202 is still appropriate for immediate acknowledgement.
Can I use 202 with a synchronous operation?
No, 202 is specifically for asynchronous operations. If you can process the request within the normal HTTP timeout (<1-2 seconds), use 200 OK instead.