HTTP 201 Created

A new resource exists as a result of this request. A well-behaved API also sends a Location header pointing at it, and usually the created representation as the body.

Defined in RFC 9110 §15.3.2 — 201 Created · MDN reference

Where you meet HTTP 201 in production

Sign-ups, orders, uploads, bookings, comments — anything where a POST leaves something behind that has an address of its own afterwards, and where the caller will very likely want to fetch or modify it a moment later.

Why you would test it

Check the Location header, not just the status — clients that build the follow-up URL themselves break the first time the server changes its id scheme.

What your client should do about a 201

Read the Location header and follow it rather than assembling the URL yourself from the id in the body. Servers change id schemes; clients that guess break on the day they do. Where the body carries the created representation, use it instead of an immediate re-fetch.

201 versus the codes it gets confused with

Endpoints that return 201

44 endpoints in this playground answer with 201. Every one is free, needs no signup, and can be called from the browser or with curl.

…and 19 more endpoints across the catalog.

Questions about HTTP 201

Does a 201 have to include a body?
No. The Location header is the important part; the body is a convenience that saves the client a round trip.
What if the resource already existed?
Then it was not created. 200 with the existing representation, or 409 if the request was an unambiguous attempt to create a duplicate.

Other success codes

All HTTP status codes · All 39 mock REST APIs · Getting started guide

Last updated