201 Created
The request succeeded and created one or more new resources, identified by the Location header.
Status
HTTP/1.1 201 Created
Details
- Category: 2xx
- Status: Standard. Registered with IANA and defined by a current standards-track RFC.
- Specification: RFC 9110 §15.3.2
- Cacheable: Only with explicit cache headers
- Response body: Allowed
- Retry: Do not retry
201 is the correct answer to a POST or PUT that brought a resource into existence. The Location header carries the URL of what was created. If more than one resource was created, Location points at the primary one and the body describes the rest.
The response should also carry validators for the new resource, so a client can immediately make conditional requests against it without a second round trip.
Headers
- Location: URL of the newly created resource. Expected on every 201.
- ETag: Validator for the created representation, useful for follow-up conditional requests.
Common causes
- A POST to a collection endpoint created a new member.
- A PUT to a URL that did not previously exist created the resource at that URL.
How to fix it
As the client
- Read Location rather than guessing the new URL from the request.
- Do not blindly retry a request that returned 201. Without an idempotency key you will create a duplicate.
As the server
- Always set Location. Clients that have to parse the body to find the new ID are working around a missing header.
- Support an idempotency key on creation endpoints so a client that lost the response can retry safely.
Examples
POST /api/v2/order HTTP/1.1
Host: api.example.com
Authorization: Bearer sk_live_example
Content-Type: application/json
{"product_id":"isp-us","quantity":10}
HTTP/1.1 201 Created
Location: /api/v2/order/40213
Content-Type: application/json; charset=utf-8
{"id":40213,"status":"provisioning","quantity":10}