What it means
A POST or PUT that created something. Send a Location header pointing at the new resource - that is the part almost everybody omits, and it is what makes 201 more informative than 200.
- Class
- 2xx Success
- Defined in
- RFC 9110 §15.3.2
- Cached by default
- Yes, without explicit headers
When you receive a 201
- Read the
Locationheader: it is the canonical URL of what you just created, and usually carries the new id. - A 201 in reply to a retried
POSTmay mean you created a duplicate. If the API accepts an idempotency key, send one.
When you send a 201
- Send it when a
POST, or aPUTto a new URL, creates a resource. - Include
Locationwith the new resource's URL - the header that makes 201 more useful than 200. - Return the created representation, or at least its id, so the client does not need a second request to find it.
On the wire
HTTP/1.1 201 Created
Location: /v1/orders/ord_8421
Content-Type: application/json
{"id": "ord_8421", "status": "pending"}