201 Created
The request has succeeded and has led to the creation of a new resource.
Usually happens because:
- ☑ Successful database inserts triggered by
- ☑ Uploading a new file to
🔍 Quick Checklist:
Meaning
The HTTP 201 Created success status code indicates that the request has succeeded and has led to the creation of a new resource. The new resource is effectively created before the response is sent back, and its URI is returned in the Location header.
Root Causes
- Successful database inserts triggered by API POST requests.
- Uploading a new file to cloud storage bucket directories.
| Cause | Frequency |
|---|---|
| Successful database inserts triggered by | ⭐⭐⭐⭐⭐ |
| Uploading a new file to | ⭐⭐⭐⭐ |
Common Mistakes
- Returning HTTP 200 OK instead of 201 Created when a resource is actually created.
- Omitting the Location header field, which is expected by REST standards.
How to Fix
Framework-Specific Examples
Returning 201 status code and Location header in Express.
app.post('/api/users', (req, res) => {
const newId = 99;
res.setHeader('Location', `/api/users/${newId}`);
res.status(201).json({ id: newId, name: req.body.name });
});Server Configuration Examples
Passing Location headers transparently from upstream application servers.
proxy_pass http://app_servers;
proxy_redirect off;Prevention
- Enforce RESTful API guidelines across your development team.
- Automate integration tests checking response headers and codes.
Frequently Asked Questions (FAQ)
Q: Should a 201 response include payload body contents?
While not strictly required, it is highly recommended to return the newly created object representation (including auto-generated IDs or database timestamps) to save clients an additional GET request.
Q: What is the purpose of the Location header in 201?
It informs the client client where the newly created resource resides so the client can query or manage it.
Q: Does a 201 Created trigger a browser redirect?
No. The browser does not navigate away; it simply receives the success confirmation. Redirects must be managed by the application JavaScript.
Q: When should I use 200 vs 201?
Use 201 Created exclusively when a new database record or file is created. For updates (PUT/PATCH), use 200 OK or 204 No Content.