Created
ActiveHTTP 201 Created indicates the request has been fulfilled and one or more new resources have been created. Defined in RFC 9110 §15.3.2. If a Location header is present, it identifies the primary newly created resource. If Location is absent, the target URI of the request identifies the primary resource.
Description
The 201 Created status code indicates that the request has been fulfilled and has resulted in one or more new resources being created. The primary resource created by the request is identified by either a Location header field in the response or, if no Location header is received, by the target URI.
The 201 response content typically describes and links to the resource(s) created.
Examples
POST /api/users HTTP/1.1
Host: api.example.com
Content-Type: application/json
{"name": "Bob", "email": "[email protected]"}HTTP/1.1 201 Created
Location: /api/users/43
Content-Type: application/json
{"id": 43, "name": "Bob", "email": "[email protected]", "created_at": "2024-01-15T10:30:00Z"}Edge Cases
- •Location header is not required. If present, it identifies the primary created resource. If absent, the target URI of the original request identifies the primary resource (RFC 9110 §15.3.2).
- •If multiple resources are created, only the primary one should be in Location.
- •201 should only be sent after the resource is fully created, not for async creation (use 202 Accepted for asynchronous processing).
When You'll See This
- →Creating a new user account
- →Adding an item to a collection via POST
- →Uploading a file and receiving the file's new URL
Implementation References
| Language | Constant |
|---|---|
| Go | http.StatusCreated |
| Rust | http::StatusCode::CREATED |
| Python | http.HTTPStatus.CREATED |
| Node.js | http.STATUS_CODES[201] |
| .NET | HttpStatusCode.Created |
| Java | HttpURLConnection.HTTP_CREATED |
History
Introduced in HTTP/1.0 (RFC 1945, 1996). Essential to RESTful API design where POST creates resources.
Related Status Codes
Related Headers
FAQ
What does HTTP 201 Created mean?
HTTP 201 Created means the request succeeded and one or more new resources were created. If a Location header is present in the response, it identifies the primary new resource. If Location is absent, the request target URI identifies it. This is defined in RFC 9110 §15.3.2.
Is the Location header required with 201?
No. RFC 9110 §15.3.2 says if no Location header is present, the target URI of the request identifies the primary resource created. Location is optional but strongly recommended for REST APIs so clients know exactly where the new resource lives.