Quick answer
HTTP 201 Created means the request succeeded and a new resource was created. The response usually includes a Location header pointing to the new resource.
What HTTP 201 means
201 Created is the correct success code for a request that creates a new resource — typically a POST to a collection endpoint. The response should include a Location header with the URL of the newly created resource, and usually returns the created resource in the body.
Common causes
- A
POSTthat creates a new record (user, order, comment, etc.) - A
PUTto a specific URL that creates the resource at that location - Any endpoint whose job is to create something new
Example JSON response
{
"id": 456,
"status": "created",
"name": "New Project",
"created_at": "2026-06-02T10:00:00Z"
}Raw HTTP response
HTTP/1.1 201 Created
Location: /api/projects/456
Content-Type: application/jsonHow to handle HTTP 201
- ✓ Read the
Locationheader to get the new resource URL - ✓ Use the returned
idfor follow-up requests - ✓ Confirm the body contains the created resource state
- ✓ Return 201 (not 200) from endpoints that create resources
Handling HTTP 201 in client code
After a successful create, read both the Location header (the canonical URL of the new resource) and the body (which usually contains the server-assigned id). Grabbing the id from the body avoids a second round-trip:
const res = await fetch('/api/projects', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ name: 'New Project' }),
});
if (res.status === 201) {
const created = await res.json(); // server-assigned id, timestamps
const location = res.headers.get('Location'); // /api/projects/456
return { created, location };
}Returning 201 in different frameworks
| Framework | How to return 201 with a Location |
|---|---|
| Express (Node.js) | res.status(201).location('/projects/456').json(obj) |
| FastAPI (Python) | @app.post(..., status_code=201) + set response.headers["Location"] |
| Spring Boot (Java) | ResponseEntity.created(uri).body(obj) |
| Rails | render json: obj, status: :created, location: obj |
201 vs 200 vs 202
201 means the resource exists now. 200 OK is generic success with no creation implied. 202 Accepted means the request was accepted for asynchronous processing and the resource may not exist yet — use it for queued/background work, not for synchronous creation.
Frequently Asked Questions
Does 201 require a Location header?
The HTTP spec recommends including a Location header pointing to the newly created resource. It is strongly encouraged and most REST clients expect it, though some APIs return only the resource body.
What is the difference between 200 and 201?
200 OK is generic success. 201 Created specifically signals that a new resource was created as a result of the request. Use 201 for successful creation so clients know a new entity now exists.
Should the 201 response include the created resource?
It is common and useful to return the created resource (including its server-assigned id) in the body, so the client does not need a second request to fetch it.
What is the difference between 201 and 202?
201 Created means the resource has been created and exists now. 202 Accepted means the request was accepted for asynchronous processing — the work is queued and the resource may not exist yet. Use 202 for background jobs and 201 for synchronous creation.
Is a Location header required on a 201?
It is strongly recommended, not strictly mandatory. The Location header tells the client the URL of the new resource so it can fetch or link to it. Most REST clients and API standards expect it on a 201, so include it whenever the resource has a canonical URL.
Working with a JSON API response?
Format and inspect any response in your browser — nothing is uploaded.