201
Success
201 Created: Indicating Successful Resource Creation
✦ The Golden Answer: The 201 Created status code means that the request was successfully processed and a new resource was created as a result. The response should include a
Location header containing the URI of the newly created resource. Optionally, the response body may contain a representation of the created resource.
When to Use 201 Created
Use 201 Created when:
- A POST request creates a new entity (e.g., new user, new blog post).
- A PUT request creates a resource at a specific URI (though PUT often returns 200 or 204).
- Any operation that results in a new resource being stored on the server.
Required Headers
The most important header for 201 is Location. It tells the client where the newly created resource can be accessed:
HTTP/1.1 201 Created
Location: /api/users/123
Content-Type: application/json
{"id":123, "name":"John Doe", "created_at":"2026-06-28T12:00:00Z"}
Example Flows
| Step | Direction | HTTP Message |
|---|---|---|
| 1 | Client → Server | POST /api/users HTTP/1.1 |
| 2 | Server → Client | HTTP/1.1 201 Created |
Best Practices
- Always include the Location header – it's the standard way to tell clients where to find the new resource.
- Optionally include the full resource – many APIs return the created object in the response body to save the client an additional GET request.
- Use 201 only for creation – if the request updates an existing resource, use 200 OK or 204 No Content instead.
- Be idempotent – if the same POST request is repeated, it should not create duplicate resources (use 409 Conflict or 422 Unprocessable Entity for duplicates).
Frequently Asked Questions
What if I don't include the Location header?
The specification strongly recommends it, but it's not strictly required. However, omitting it makes the response less useful for clients, as they have no standard way to know the URI of the new resource.
Can I return a 201 Created with an empty body?
Yes, but it's less common. Usually you either return the created resource or a simple confirmation. If you return an empty body, make sure to set Content-Length: 0.
Should I use 201 for file uploads?
Yes, if the upload results in a new resource (e.g., a stored image). Return a Location pointing to the uploaded file's URL, and optionally return metadata about the file.