201Created
The request worked and made something new, usually named in the Location header.
How you get a 201
A POST asks the app to create an order. The app writes it to the database, then the app sends 201 with a Location header pointing at the new order.
Who sends itApp
- Browser
- CDN
- Proxy
- App
- DB
Typically the application, after it has stored the new thing. Proxies and CDNs pass it along and do not cache it.
In short
What a 201 Created means
A 201 Created says the request succeeded and one or more new resources now exist because of it. It is the normal answer to a POST that creates something, and to a PUT that stores something at a URL that had nothing before. The response should say where the new resource lives, usually in a Location header, and often includes the resource in the body. The application sends it, after the write has reached the database. The thing to remember is that creating is not repeatable. If the client loses the response and sends the same POST again, the server creates a second copy and answers 201 again. Safe retries need an idempotency key, or a PUT to a URL the client chose.
When you see a 201
1A POST created a new record.
How to check: The Location header gives its address. Fetch it to confirm.
curl -si -X POST https://example.com/api/orders -d @order.json | grep -i location2A PUT stored something at a URL that was empty before.
How to check: The same PUT a second time should answer 200 or 204, because now it replaces.
3A retry or double click created a duplicate.
How to check: Look for two records with the same contents a few seconds apart.
SELECT * FROM orders WHERE customer_id = 42 ORDER BY created_at DESC LIMIT 5;
Retry or not?
Nothing to retry · Do not resend the POST
Headers that matter
- Location
- The address of the new resource. If it is missing, the RFC says the new resource is at the URL you posted to.
- ETag
- The version of what was just created, useful for a later conditional update.
- Idempotency-Key
- A request header by convention, not part of RFC 9110. It lets the server spot a repeated create and return the first result.
In the real world
RFC vs real deployments
RFC 9110 expects 201 for a successful create, with the new address in Location. Many APIs simply return 200 for everything, and many 201 responses leave Location out. Both work for a client that reads the body, but generic tooling loses the signal that something new exists.
Seen in a real outage
Creating twice is an ordinary failure, not an exotic one. On Christmas Day 2021 Santander sent 75,000 payments a second time, £130 million in total, because a batch was processed twice.
Your turn
Which code is it?
A mobile app posts a new order, the connection drops before the response arrives, and the app sends the same POST again. Both attempts reach the server. What happens by default?
201 questions
- What is the difference between 200 and 201?
- Both mean success. A 201 adds a fact: a new resource was created by this request, and the response should say where it is.
- Who sends a 201 Created?
- Typically the application, once the new record has been stored. Proxies and CDNs only pass it along.
- Is it safe to retry a request that returned 201?
- There is no need to: it already worked. Resending the same POST usually creates a duplicate, unless the API supports idempotency keys.
Sources: RFC 9110: 201 Created (section 15.3.2) ↗ · RFC 9110: Location (section 10.2.2) ↗ · RFC 9110: Idempotent methods (section 9.2.2) ↗ · Report a problem
Diagrams are our own simulations. All wording is original and paraphrases the linked sources.
Practise this in the DNS / HTTP track
Two-minute animated lessons, then boss fights from real outages. Free, no account needed.