HTTP 201 Created
Success response for creation: a new resource now exists, and Location says where.
What HTTP 201 means
HTTP 201 Created is returned when a request — almost always a POST or PUT — successfully created a new resource on the server. REST APIs use it to distinguish “something new now exists” from the generic 200 success.
A proper 201 response includes a Location header with the URL of the newly created resource, and often echoes the created object in the body so the client does not need a follow-up GET.
Common causes of 201 responses
- A POST request created a record, file or account.
- A PUT request created a resource at the exact URL supplied by the client.
- A batch endpoint finished creating one primary resource synchronously.
Good practices for developers
- Set the Location header to the canonical URL of the new resource.
- Return the created representation (with its server-assigned id) in the body to save clients a round trip.
- If creation is queued rather than finished, return 202 Accepted instead.
- Repeated identical POSTs creating duplicates? Consider idempotency keys and answer 200/409 for replays.
Example response
HTTP/1.1 201 Created
Location: /api/users/1024
Content-Type: application/json
{"id":1024,"name":"New user"}FAQ
What is the difference between 200 and 201?
Both mean success, but 201 specifically tells the client a new resource was created. 200 just means the request was processed.
Is the Location header required with 201?
It is strongly recommended: it points to the URL of the newly created resource so clients can fetch or link it.
When should an API return 202 instead of 201?
When creation happens asynchronously — 202 means the request was accepted but the resource does not exist yet.