HTTP 201 Created

Quick reference

When to return 201

Return 201 whenever a POST request creates a new resource that is now addressable — a new user, order, document, record, or any entity with a URL. Return 201 from a PUT request only when the resource did not previously exist and was created by that PUT. If a PUT updates an existing resource, return 200 or 204 instead.

Do not return 201 when no new resource was created. A login endpoint succeeds without creating a new resource — that is 200. A delete endpoint removes a resource — 200 or 204. An update endpoint modifies an existing resource — 200 or 204. 201 is specifically for creation.

The Location header

RFC 9110 says the server SHOULD include a Location header in a 201 response. The header value is the URL of the newly created resource — the URL a GET request would hit to retrieve it.

HTTP/1.1 201 Created
Location: https://api.example.com/users/4821
Content-Type: application/json

{
  "id": 4821,
  "email": "user@example.com",
  "created_at": "2026-04-25T10:30:00Z"
}

The URL in Location should be absolute. The response body here contains the same data a GET to that URL would return, saving the client a follow-up request. RFC 9110 allows but does not require a body with 201.

Omitting the Location header is technically valid but forces clients to parse the body to extract the new resource's ID and construct the URL themselves. Always include it in REST APIs.

Common mistakes

Returning 200 instead of 201

The most common error. The client gets its data, but the semantic signal is lost. 201 specifically tells tools, documentation generators, and client libraries that a new addressable resource was created. A 200 from a creation endpoint is technically wrong per RFC 9110 semantics.

201 from PUT on an existing resource

A PUT to an existing URL that updates the resource should return 200 or 204, not 201. Returning 201 on every PUT regardless of whether the resource was created or updated incorrectly signals creation on updates. Check whether the resource existed before the PUT and respond accordingly.

201 for bulk creation

When a single request creates multiple resources, there is no single URL for the Location header. Use 200 with a body listing the created URLs, or 202 if creation is asynchronous. Alternatively, design bulk creation as multiple requests.

Missing Location header in framework responses

Some frameworks and ORMs return 201 automatically without setting Location. Check that your serializer or response builder includes the header. In Express: res.location('/users/' + user.id).status(201).json(user). In Django REST Framework: the CreateModelMixin sets Location automatically when get_success_url is defined.

201 vs 200 vs 202 vs 204

Framework examples

Express (Node.js)

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

Django REST Framework

class UserCreateView(CreateAPIView):
    serializer_class = UserSerializer
    # CreateAPIView automatically returns 201
    # Set get_absolute_url() on the model for Location header

Go (net/http)

w.Header().Set("Location", "/users/"+strconv.Itoa(user.ID))
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(http.StatusCreated)
json.NewEncoder(w).Encode(user)

Related guides

HTTP 200 OK · HTTP 202 Accepted · HTTP 204 No Content

Comparisons

200 vs 201 · 201 vs 202

Standards reference

Definitions from the IANA HTTP Status Code Registry and RFC 9110 §15.3.2. Human-readable guidance by ErrorLookup. · HTTP 201 quick reference →