201 Created

What 201 means

201 signals that a new resource now exists as a result of the request. It is the correct response to a POST that creates something, and to a PUT that creates a resource at the target URL rather than replacing one.

The specification expects a Location header giving the URL of the new resource, and this is the part most often omitted. Without it, a client that has just created something has no standard way to find out where it lives - it has to guess from the body, which couples it to your serialisation format.

The response body conventionally contains a representation of the created resource, which saves the client an immediate follow-up GET.

Headers this status expects

• Location - the URL of the newly created resource. Frequently omitted; include it.
• ETag - lets the client do conditional updates immediately without a fetch first.

Should a client retry?

Do not blindly retry a request that returned 201 - you will create a second resource. This is what idempotency keys exist for.

FAQ

Does 201 require a Location header?

The specification says the response should include one identifying the created resource, and it is the main thing that distinguishes a useful 201 from a bare 200. It is also the most commonly omitted part.

What if a retried POST would create a duplicate?

Use an idempotency key: the client sends a unique key with the request, and the server returns the original result for a repeat of the same key rather than creating a second resource. Stripe's API is the canonical example.

Often confused with

• 200 OK The request succeeded and the response carries the result.
• 202 Accepted The request was accepted for processing, but has not been completed yet.