HTTP 201 Created

What 201 means

When to return 201, and when not to

• POST /users inserted a new row: return 201 with Location: /users/123.
• PUT /files/report.pdf uploaded a file to a new path: 201. Replacing an existing file is 200 or 204.
• The work was only queued (a video transcode, a bulk import): it's not created yet. Return 202 Accepted with a URL the client can poll.
• The POST was an action that created nothing (search, login, sending an email): return 200.
• The resource already existed (duplicate unique key): return 409 Conflict, or point to the existing resource if your API is idempotent by design.

How to return a 201

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

// app/api/users/route.ts
export async function POST(request: Request) {
  const input = await request.json();
  const user = await createUser(input);
  return Response.json(user, {
    status: 201,
    headers: { Location: `/api/users/${user.id}` },
  });
}

curl -i https://api.example.com/users \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 6f1c2a4e-9b1d-4c1e-8a57-1f0e2b7d9c11' \
  -d '{"email":"ada@example.com"}'

HTTP/1.1 201 Created
Location: /users/123
Content-Type: application/json

Headers that matter with 201

Location

The URL of the new resource. It can be relative, e.g. /users/123.

Access-Control-Expose-Headers

Location isn't a CORS-safelisted response header, so a cross-origin fetch() can't read it unless the server sends Access-Control-Expose-Headers: Location.

ETag / Last-Modified

If sent with a 201, they describe the newly created resource, so the client can make a conditional update straight away.

201 vs similar status codes

• 200 OK: Generic success. Fine for actions that return a result, but loses the "something was created" signal.
• 202 Accepted: The request was accepted but the resource doesn't exist yet. Return a status URL instead of the resource.
• 409 Conflict: The resource you tried to create already exists, or clashes with the current state.

Related status codes

Looking for another code? Search the full HTTP status codes list, or read which code your API should return in the REST API status codes guide.

Learn more

Browse all developer guides →

Frequently Asked Questions