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.
Usage notes
For clients
- 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.
For servers
- 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
Creating a resource with POST
A POST that creates an order:
HTTP request
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}
The response reports where the new resource lives in the Location header:
HTTP response
HTTP/1.1 201 Created
Location: /api/v2/order/40213
Content-Type: application/json; charset=utf-8
{"id":40213,"status":"provisioning","quantity":10}