HTTP status codes are more than small numbers returned by a server. They set expectations between an API provider and a client application, especially when data is created, processed, queued, or delayed. Two codes that are often confused are 201 Created and 202 Accepted. Both can appear after a successful request, but they communicate very different outcomes.
TLDR: Use 201 Created when the requested resource has already been created successfully, such as a new user account or invoice record. Use 202 Accepted when the request has been received but processing is still pending, such as a video export job or bulk email campaign. For example, if an API receives 10,000 image uploads and queues them for background optimization, returning 202 is more accurate than 201 because the final processed assets do not yet exist.
What HTTP 201 Created Means
201 Created means the server has successfully fulfilled the request and created a new resource. It is commonly returned after a POST request, although it can also be used with other methods when appropriate. The important point is that the resource exists by the time the response is sent.
A typical example is user registration. A client sends user details to /users, and the server creates a new user with an ID such as 8421. The response can then return 201 Created and include the newly created resource or a reference to it.
- Request:
POST /users - Result: A new user account is created immediately
- Response:
201 Created - Location header:
/users/8421
The Location header is especially important with 201 responses. It tells the client where the new resource can be found. While not always strictly required in every implementation, it is strongly recommended for clear and predictable API behavior.
What HTTP 202 Accepted Means
202 Accepted means the server has accepted the request for processing, but the processing has not been completed yet. Unlike 201, it does not confirm that a resource has been created. It only confirms that the request was valid enough to be accepted into the system.
This status code is useful for asynchronous operations. These are tasks that may take several seconds, minutes, or even hours to complete. Examples include generating reports, processing payments through external providers, transcoding videos, importing thousands of records, or sending large email campaigns.
- Request:
POST /reports - Result: A report generation job is queued
- Response:
202 Accepted - Follow-up: The client checks job status later using a tracking URL
A strong 202 response should usually provide a way to monitor progress. For example, it may return a job ID, a status endpoint, or an estimated completion time. Without this, the client knows the request was accepted but has no reliable way to understand what happens next.
The Core Difference: Completed vs Pending
The key difference between 201 and 202 is simple: 201 means the creation has happened, while 202 means the request has been accepted but the final result is still pending.
This distinction matters because clients often make decisions based on status codes. If an API returns 201, the client may immediately attempt to fetch, display, update, or reference the new resource. If the resource is not actually available yet, that creates confusion and potential errors. In contrast, 202 tells the client to wait, poll a status endpoint, or listen for a webhook.
| Status Code | Meaning | Best Used When |
|---|---|---|
| 201 Created | A resource has been created | The resource is available immediately |
| 202 Accepted | A request has been accepted for later processing | The task is queued or still running |
Practical API Examples
Consider an e-commerce platform. When a customer creates a shipping address, the API can usually store it immediately. In that case, 201 Created is appropriate because the address record exists as soon as the server responds.
However, consider an order fulfillment request that triggers fraud checks, warehouse allocation, payment verification, and third-party shipping calculations. If the system accepts the order but still needs to complete those steps, 202 Accepted is safer and more accurate. It avoids making a premature promise that the order has been fully processed.
A realistic scenario might look like this: a SaaS analytics platform receives a request to export 2 million rows of customer activity data. Internal benchmarks show that 78% of exports finish within 90 seconds, but larger exports may take up to 12 minutes. Returning 202 Accepted with a job ID allows the client to show a progress state instead of timing out or assuming the export file is ready.
Common Mistakes When Using 201 and 202
One common mistake is returning 201 Created too early. If a server only places a task into a queue, but the resource will be created later by a worker process, 201 is misleading. The correct response is usually 202, because the final result is not guaranteed at response time.
Another mistake is using 202 Accepted without any follow-up mechanism. A 202 response should not leave the client guessing. At minimum, it should include some combination of the following:
- A job identifier, such as
jobId - A status URL, such as
/jobs/abc123 - A current status, such as
queuedorprocessing - An estimated completion time, when reasonable
- A webhook option, for notifying the client when processing finishes
It is also important not to treat 202 as a guarantee of success. A request accepted for processing may still fail later. For example, a video upload may be accepted, but the encoding process may fail because the file is corrupted. The status endpoint should be able to report final states such as completed, failed, or cancelled.
When to Choose 201 Created
Choose 201 Created when the server has already created the resource and the client can use it immediately. This is appropriate for straightforward creation workflows, such as:
- Creating a new customer profile
- Adding a product to a catalog
- Saving a billing address
- Creating a comment, ticket, or message
- Registering a device or API key
A good 201 response is direct and confident. It should usually include the new resource representation, its unique identifier, and a Location header pointing to the resource URL.
When to Choose 202 Accepted
Choose 202 Accepted when processing is delayed, delegated, queued, or dependent on another system. This is common in distributed architectures where the API gateway, application server, queue, worker, and database may all play separate roles.
Good use cases include:
- Generating large PDF or CSV reports
- Processing media files
- Starting machine learning jobs
- Triggering bulk imports or exports
- Submitting requests to third-party payment or compliance systems
In these cases, the API should communicate that the process has begun but is not finished. This helps clients handle the workflow responsibly, whether by polling, waiting for a webhook, or displaying a pending state to the user.
Final Takeaway
201 Created and 202 Accepted both indicate that a request has passed an important success threshold, but they should not be used interchangeably. 201 is about completed creation; 202 is about accepted processing. The best choice depends on the actual state of the resource at the moment the server sends the response.
Using these codes correctly makes APIs more predictable, reduces client-side errors, and improves trust between systems. If the resource is ready, return 201 Created. If the work is still underway, return 202 Accepted and provide a clear path for the client to track the result.