201 Created

HTTP 201 Created confirms that a request, almost always a POST or occasionally a PUT, resulted in one or more new resources coming into existence. The spec expects the server to include a Location header pointing at the primary resource that was created, so the client can immediately address it in follow-up requests without having to guess or parse an ID out of the body. The response body is optional but conventionally contains a representation of the newly created resource, letting the client see server-assigned fields like an ID, timestamps, or computed values in the same round trip that created them.

This status is central to REST API design: a POST to a collection endpoint such as /orders that succeeds in creating a new order should return 201 with Location: /orders/8842 and a JSON body describing that order, rather than 200 with the same information. Using 201 specifically, instead of a generic 200, lets clients, SDKs, and API gateways distinguish create operations from reads or updates purely from the status line, which matters for idempotency handling, retry logic, and audit logging that treats creation as a distinct event from other successful writes.

A common source of confusion is PUT: when a PUT request creates a resource at a client-specified URL that did not previously exist, 201 is the correct response, with 200 or 204 reserved for a PUT that updated an existing resource. Because PUT is defined to be idempotent, a server that supports upsert-style PUT needs to check for prior existence before choosing between these codes. Frameworks that generate 201 automatically for any successful insert can get this wrong if the same handler also serves updates to existing rows.

201 responses are not cached by shared caches under normal rules, since a create operation is not considered safe to reuse for a different request, though the created resource itself becomes cacheable on subsequent GETs like any other resource. API clients and SDK generators frequently key their generated model classes off whether an endpoint returns 201, so omitting the Location header or returning an inconsistent body shape on creation tends to break tooling downstream even when the status code itself is correct.