201 Created
The request succeeded and created one or more new resources. The Location header carries the URL of the primary one.
At a glance
- Status code
- 201 Created
- Class
- 2xx, success, the request was received and accepted
- Defined in
- RFC 9110
- Cacheable by default
- by explicit headers only
- Response body
- Usually a representation of the new resource.
In detail
201 says something now exists that did not exist before the request. The Location header is the whole point of the code: without it the client has to guess the identifier of the thing it just made.
Correct for a POST to a collection that mints a new identifier, and for a PUT to a URL that did not previously resolve. A PUT that replaces an existing resource returns 200 or 204 instead.
If a client cannot find the new record, check that Location is absolute or a valid relative reference, and that CORS exposes it. Location is not on the default safelist for cross-origin reads.
Examples
HTTP/1.1 201 Created
Location: /api/orders/8812
Content-Type: application/json
{"id":8812}Things that catch people out
- In a cross-origin request the browser hides Location unless the server sends Access-Control-Expose-Headers: Location. The response looks empty and the bug looks like a server fault.
- Repeating a POST that returns 201 creates a second resource. If retries matter, use an idempotency key rather than relying on the status code.
Try it: HTTP Request Builder
Build a request with any method, headers and body, send it, and read the status line the server returns.
HTTP Request Builder
LOCAL · Browser-OnlyBuild and test HTTP requests with custom headers and body
Authentication
Headers
Generate Code
curl -X GET 'https://api.example.com/endpoint' \
-H 'Content-Type: application/json'Showing a sample URL. Enter your endpoint above to update the snippet.
Related HTTP status codes
All http status codes →200 OK
The request succeeded. What the body contains depends on the method: a GET returns the resource, a POST returns the result of the action.
202 Accepted
The request was accepted for processing but is not finished, and may still fail. Nothing has necessarily happened yet.
409 Conflict
The request clashes with the current state of the resource, for example an edit based on a version that has since changed.
203 Non-Authoritative Information
The request succeeded, but a proxy between you and the origin server altered the response body or headers.
204 No Content
The request succeeded and there is deliberately nothing to send back. The browser stays on the current page.
205 Reset Content
The request succeeded and the client should clear the form that sent it, ready for another entry.
Tools for this
- HTTP Request Builder Free online HTTP request builder - build and test HTTP requests with custom headers and body
- HTTP Headers Checker Free online HTTP headers checker - view HTTP response headers for any URL