The number 202 is a common status code that you may see when working with web APIs or other online services. Specifically, 202 is an HTTP status code that means “Accepted”.
What is an HTTP status code?
HTTP stands for Hypertext Transfer Protocol. It’s the underlying protocol that powers the World Wide Web. Whenever you visit a website, your browser sends a HTTP request to the server hosting that site. The server then responds with a HTTP response.
Part of the HTTP response is a status code. Status codes are 3-digit numbers that indicate whether the request succeeded or failed in some way. Here are some common status codes you may have seen:
- 200 OK – The request succeeded
- 301 Moved Permanently – The resource has moved to a new URL
- 400 Bad Request – The request was malformed or invalid
- 401 Unauthorized – Authentication is required
- 403 Forbidden – Access to the resource is forbidden
- 404 Not Found – The resource does not exist
- 500 Internal Server Error – The server encountered an unexpected error
As you can see, status codes belong to one of the following ranges:
- 1xx Informational
- 2xx Success
- 3xx Redirection
- 4xx Client Error
- 5xx Server Error
The specific status code helps the client (e.g. the web browser) determine what happened with the request. Status codes in the 200 range mean the request was successful in some way. The 404 status code indicates a common client error, for example.
What does 202 Accepted mean?
Now that we’ve gone over the basics of status codes, let’s get back to 202. The 202 Accepted status code indicates that the request has been accepted for processing, but the processing has not yet been completed.
Here are some key things to know about 202 Accepted:
- The request has been validated and accepted by the server for processing.
- Processing of the request has not yet been completed.
- The 202 response is non-committal – it does not guarantee the requested action will succeed.
- The final outcome of the request is not known.
- The server provides no information about when processing will be finished.
In summary, 202 means “I have received your request and will work on processing it, but I cannot promise anything about when it will be done or if processing will succeed.”
When is 202 Accepted used?
The 202 Accepted status code is useful in situations where processing a request may take a long time, and immediate success or failure is not known. Here are some examples of when servers may return a 202 status code:
- When an API request needs to be queued for background processing
- When initiating long-running operations such as uploading large files
- When asynchronously processing expensive or time-consuming computations
- When scheduling resource-intensive tasks to be performed in the future
A 202 Accepted response indicates the request will be worked on sometime later. It relieves the client from needing to wait for the full processing to complete before receiving a response. The client can track progress in other ways such as checking status at a later time.
Example API Use Cases
Here are some more concrete examples of how APIs commonly use 202 Accepted responses:
Asynchronous Processing
An API for transcoding videos may allow clients to submit files for transcoding. Since transcoding can be resource-intensive and take a long time, the API responds with 202 Accepted to indicate the video is now in a processing queue. The client can poll the API status endpoint later to see when processing is finished.
Queued Tasks
An API for submitting batch data analysis jobs may place requests in a queue to be worked on. A 202 indicates the job is accepted and queued, while results will be available later once processing completes. The client can use the job ID to check the status rather than waiting for completion.
Deferred Responses
An API that returns responses from a slow database may use 202 to indicate the response generation has been deferred. This allows the API to respond immediately while database processing continues asynchronously.
Long-Running Operations
An API that initiates long-running operations like launching cloud instances may use 202 to confirm the operation is in progress. The client can check the status endpoint later to see when the operation is complete.
When is 202 Accepted response used instead of 200 OK?
Since 202 Accepted indicates the request is still being processed, you may wonder when it should be used instead of 200 OK which indicates success. Here are some general guidelines on when to return 202 vs 200:
- 200 OK – Return this when the request is completed and a response is available to return immediately.
- 202 Accepted – Return this when more processing is needed that will complete asynchronously. The final result is not ready yet.
In summary:
- 200 OK – Request received and completed immediately with a response available now.
- 202 Accepted – Request received but more processing still required. Response not ready yet.
The 202 status codes buys time for asynchronous processing when requests cannot succeed or fail immediately. The tradeoff is the client must wait and check back later for the actual result.
Should a 202 response have a body?
The HTTP specification does not define any requirements for the body content of a 202 Accepted response. However, here are some common approaches:
- No body – Omit the body altogether and simply return the 202 status code.
- Empty body – Include an empty response body.
- Status body – Include information about the pending request’s status or next steps.
- Progress body – Include partial results or progress indicators if available.
Including an empty or status body provides a way to communicate extra information about the pending operation. But a body is not required – a 202 status code by itself is sometimes sufficient.
Example 202 Response Bodies
Here are some examples of extra detail you could include in the body of a 202 response:
- A request or operation ID to track status.
- A link to poll for status updates.
- Expected time estimate for completion.
- Progress percentage if available.
- Status, state, or phase of the request.
- A link to cancel or delete the pending request.
Including supplementary information like this can help clients track progress and next steps.
Should a 202 response be cacheable?
Responses with a 202 status code should have the HTTP Cache-Control header set to no-store. This prevents caching of the 202 response.
Here is an example using the Cache-Control response header:
“`
HTTP/1.1 202 Accepted
Cache-Control: no-store
“`
This is done because a 202 indicates processing is still occurring. Caching should be prevented since the response body may become outdated or invalid once processing completes later.
When processing does complete, the final representation can be cached if appropriate. But intermediary 202 responses while processing is still underway should not be cached.
Can a 202 response be retried?
There are no hard rules for whether a client should retry a request that received a 202 Accepted response. It depends on the particular API and use case.
In some cases, it may be safe for clients to retry a request that got a 202 since it indicates the initial request was accepted but processing has not finished. Retrying may amount to just having two instances of the same request in the processing queue.
However, for operations that are not idempotent, retrying may cause unwanted side effects. For example, retrying a request to charge a credit card twice or launch two cloud instances.
In summary:
- Idempotent requests – Usually safe to retry 202 requests.
- Non-idempotent requests – Unsafe to retry due to risk of side effects.
To avoid unwanted side effects, it’s best to avoid retrying non-idempotent 202 requests. Check the API documentation for guidance.
How can clients track status of 202 requests?
Since a 202 Accepted response indicates asynchronous processing, clients will likely want to track the status of their request. Here are some common ways APIs enable clients to check the status:
Poll the Status Endpoint
Many APIs provide status endpoints that allow clients to poll for updates on a pending request. The API may require passing a request ID to check that specific status. Polling provides updates once processing completes.
Webhooks
APIs may support webhooks or callbacks to push status updates to the client. This allows asynchronous notifications instead of polling.
Status Query Parameter
Some APIs return a status query parameter like &status=pending with the 202. Clients can check this endpoint later passing the status parameter to get updates.
Monitor Resource State
For requests that modify or create a resource, clients can monitor the state of the resource to see when it changes due to completed processing.
Should clients have timeouts for 202 requests?
It’s generally wise for clients to implement timeouts when waiting for 202 requests to complete. Some reasons why:
- Processing that takes too long may indicate a failure stuck in progress.
- APIs may have internal timeouts that abort processing after a set time period.
- Timeouts prevent clients from waiting indefinitely for a result.
- Timeouts allow clients to handle stuck progress and retries.
Common timeout patterns include:
- Retry timeout – How long to wait before retrying a request that hasn’t completed yet. For example, retrying every 5 minutes.
- Total timeout – Total time to wait for a request to succeed before considering it failed. For example, 30 minutes.
- Callback timeout – How long to wait for a webhook callback before checking status through polling.
Reasonable timeouts prevent clients from waiting forever. Endpoints that regularly exceed expected timeouts may indicate systemic problems.
Are multiple 202 responses allowed?
It is possible for an API to return multiple 202 Accepted responses for a single client request. This indicates the request is being processed asynchronously in multiple discrete steps or phases.
For example, an API could:
- Accept request and validate input – Return 202 Accepted.
- Start asynchronous processing – Return 202 Accepted.
- Complete first phase of processing – Return 202 Accepted.
- Complete all processing – Return 200 OK with final response.
Returning multiple 202 responses can keep the client updated about different stages of progress. Each 202 indicates another portion of processing has started but not yet finished.
The tradeoff is more complexity for clients to handle multiple status updates. There also needs to be a clear final response like 200 OK when processing ultimately completes.
Common mistakes using 202 Accepted
While 202 Accepted is designed to indicate asynchronous processing, there are some misuses and mistakes to be aware of:
Using 202 when immediate response is available
Don’t use 202 if the request can be completed immediately. Use 200 OK with the response body for requests with instant responses available.
Not informing client of status
Don’t leave clients hanging after a 202 without a way to check request status later. Provide status endpoints, callbacks, or tracking identifiers.
Allowing unbounded wait times
Don’t make clients wait indefinitely. Have reasonable timeouts and limits on total processing time.
Forgetting to return final success result
Don’t forget to return a final success response like 200 OK when processing fully completes in the future.
Returning 202 on partial success
Don’t use 202 to indicate partial success or failure. Use more specific status codes like 207 Multi-Status for mixed results.
Conclusion
The 202 Accepted status code is a useful way for APIs to indicate asynchronous processing and deferred responses. It allows servers to offload long-running tasks without making clients wait for completion before receiving a response.
However, 202 Accepted responses should include guidance on how clients can track status and be designed thoughtfully to provide a good developer experience. Used properly, 202 enables APIs to handle time-consuming workflows in a scalable, non-blocking way.
To summarize key points:
- 202 Accepted indicates a request is received for processing but completion will occur later asynchronously.
- Use it for long-running requests where the final result is not instantly available.
- Include status tracking information and timeouts to prevent indefinite waiting.
- Return a final response like 200 OK when processing finishes in the future.
- 202 enables asynchronous workflows and deferred responses.
Following these best practices for 202 Accepted responses will lead to efficient yet developer-friendly APIs.