HTTP 201 Created: when to return it (vs 202)

HTTP response code 201 (Created) means the request succeeded and a new resource was created. It is commonly sent after POST and sometimes PUT when a new resource exists by the time the server replies. The new resource must be locatable by the request URL or by the URL in the Location header included in the response MDN 201 Created.

201 vs 202 (and a quick 200 note)

Use 201 when the server has created the resource as a result of the request and it is available to locate right away. MDN summarizes: “The request succeeded, and a new resource was created as a result” MDN response status codes.

• 201 Created: creation finished; typically for POST, or some PUT that creates a new resource MDN response status codes.
• 202 Accepted: the request was received but not yet acted upon; intended for cases handled asynchronously or by another process. It is noncommittal, since HTTP cannot later send an async outcome MDN response status codes.
• 200 OK: success without implying a new resource was created; common for GET, and for updates that return a representation MDN response status codes.

What to include in a 201 response

When you return 201, include enough information for the client to discover the new resource:

• Location header: provide the canonical URL of the created resource when it differs from the request URL. The new resource must be locatable by the initiating request URL or by Location MDN 201 Created.
• Response body: you may return the created representation. Clients should be prepared for either case (body present or absent) and treat the Location URL as authoritative when provided MDN 201 Created.

Need to check headers in the browser while developing? See How to check HTTP response headers in Chrome.

Worked example: synchronous creation (201)

POST /items HTTP/1.1
Host: api.example.com
Content-Type: application/json

{"name":"notebook","color":"navy"}

HTTP/1.1 201 Created
Content-Type: application/json
Location: https://api.example.com/items/123

{"id":123,"name":"notebook","color":"navy"}

This response makes the canonical URL explicit via Location and returns the representation for immediate use MDN 201 Created.

Worked example: asynchronous acceptance (202)

For long-running work, respond with 202 to signal that processing will complete later. A practical pattern is to return a URL clients can poll for status.

POST /reports HTTP/1.1
Host: api.example.com
Content-Type: application/json

{"range":"2026-Q3"}

HTTP/1.1 202 Accepted
Content-Type: application/json

{"jobId":"job_7f9","statusUrl":"https://api.example.com/jobs/job_7f9"}

Semantics: the request was received but not yet acted upon MDN response status codes. Do not use 201 here because the report is not yet created.

Common mistakes to avoid

• Returning 201 for queued work. If creation is not complete, use 202 Accepted MDN response status codes.
• Omitting Location when the canonical URL differs from the request. If clients cannot infer the new URL from the request URI, include Location so they can discover it reliably MDN 201 Created.
• Assuming a body is always present. Many APIs include the created object, but clients should handle an empty body with Location as the discovery mechanism MDN 201 Created.

If your clients will retry POSTs, consider idempotency keys so safe retries do not create duplicates. Our explainer covers the pattern: What is an idempotency key in APIs?

How to decide in practice

1. Did your server finish creating a new resource now? Return 201 Created and include Location when you can MDN 201 Created.
2. Is the work deferred or handled by another process? Return 202 Accepted and document how the client learns completion MDN response status codes.
3. Was this a pure read or an update with no new resource? Return 200 OK (or 204 for no-body updates) MDN response status codes.

Ship correct 201/202 responses

• Return 201 only when creation has finished and the resource is available
• Set Location to the canonical URL of the new resource when it differs from the request URL
• Include the created representation in the body or document that the body may be empty
• Use 202 for asynchronous jobs and document how clients learn completion
• Add tests that follow Location and tolerate absent bodies

Why trust these definitions?

The official registry lists 201 Created and 202 Accepted under RFC 9110 HTTP Semantics. Use it as the canonical reference when documenting your API IANA status code registry.