201 Created - HTTP Status Code

Meaning & Description

The HTTP `201 Created` success status response code indicates that the request has succeeded and has led to the creation of a resource. The new resource, or a description and link to the new resource, is effectively created before the response is sent back and the newly created items are returned in the body of the message, located at either the URL of the request, or at the URL in the value of the `Location` header.

Common Causes

A client successfully submitted a POST or PUT request containing valid data for a new resource.

How to fix a 201 error

Inspect the Location header to find the URI of the newly created resource.
Check the response body for the representation of the created entity, which may include auto-generated IDs.

Browser & SEO Behaviour

Browser Behavior

Browsers typically treat 201 Created similar to 200 OK. They do not automatically navigate to the URL in the Location header.

SEO Impact

Neutral. Search engines primarily index GET requests, so they rarely encounter 201 Created responses.

CDN Behavior

Most CDNs will not cache a 201 Created response by default since it usually replies to a POST request.

Code Examples

Raw HTTP

HTTP/1.1 201 Created
Date: Mon, 23 May 2026 22:38:34 GMT
Content-Type: application/json
Location: /api/users/123
Content-Length: 32

{"id": 123, "status": "created"}

Node.js (Express)

app.post('/api/users', async (req, res) => {
  const newUser = await db.users.create(req.body);
  res.status(201).location(`/api/users/${newUser.id}`).json(newUser);
});

Python (FastAPI)

from fastapi import FastAPI, Response, status

app = FastAPI()

@app.post("/api/users", status_code=status.HTTP_201_CREATED)
def create_user(response: Response):
    new_user_id = 123
    response.headers["Location"] = f"/api/users/{new_user_id}"
    return {"id": new_user_id, "name": "Alice"}

Go (net/http)

func createUser(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Location", "/api/users/123")
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(http.StatusCreated)
    w.Write([]byte(`{"id": 123}`))
}

C# (ASP.NET Core)

[HttpPost]
public IActionResult CreateUser([FromBody] UserDto user)
{
    var newId = 123;
    return Created($"/api/users/{newId}", new { id = newId });
}

cURL

curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice"}' -i

Raw HTTP Response Example

HTTP Response

HTTP/1.1 201 Created
Date: Mon, 23 May 2026 22:38:34 GMT
Location: /api/users/123
Content-Type: application/json
Content-Length: 42

{"id": 123, "name": "Alice"}

Real-world Examples

Stripe API: Returns 201 Created when a new payment intent or customer is successfully created.

GitHub API: Returns 201 Created when a new repository, issue, or pull request is successfully opened.

Frequently Asked Questions

What is the difference between 200 OK and 201 Created?

While both indicate success, 201 Created specifically communicates that a new resource was generated on the server as a direct result of the request. 200 OK is a generic success indicator.

Is the Location header mandatory for a 201 response?

The RFC states that the primary resource created by the request should be identified by a Location header field. While not strictly mandatory to pass syntax checks, it is a critical REST API best practice.

Can I return a response body with 201 Created?

Yes, it is common and recommended to return a representation of the newly created resource in the response body, often including auto-generated fields like IDs and timestamps.

Should PUT requests return 201 Created?

Yes, if a PUT request creates a completely new resource at a specific URI, the server should return 201 Created. If it updates an existing resource, it should return 200 OK or 204 No Content.

How do browsers handle the Location header in a 201 response?

Unlike 3xx redirects, browsers do not automatically follow the Location header of a 201 response. Your front-end JavaScript must read the header and handle navigation manually if desired.

Did You Know?

The 201 Created status was part of the original HTTP/1.0 specification in 1996.

It is one of the few success status codes that explicitly asks for a specific HTTP header (Location) to accompany the response.

Developer Tips

Always include the Location header. It saves the client from having to parse the response body just to find the ID of the new resource.
Return the complete, newly created object in the response body. This prevents the client from needing to make an immediate GET request to fetch default values or timestamps.
Use absolute URLs in the Location header rather than relative paths, as some older HTTP clients struggle with relative resolution.

Interview Questions

These are questions you might face in a backend or API design interview that touch on HTTP 201.

When designing a REST API, when would you choose 201 Created over 200 OK?

I would use 201 Created when a POST or PUT request results in the generation of a new resource on the server. I would accompany it with a Location header pointing to the new resource. I would use 200 OK for generic successes, like GET requests or updates that do not create new entities.

What information must be included in a 201 Created response according to best practices?

A 201 response should include a Location header containing the URI of the newly created resource, and preferably a response body containing the representation of the new resource (like its ID and generated fields).

Common Interview Mistakes

Saying that a 201 Created response automatically redirects the browser to the new resource. Browsers only automatically follow Location headers on 3xx responses.
Claiming that 201 Created can only be returned by POST requests. PUT requests can also return 201 if they create a resource at a previously empty URI.