201 Created

This is an educational reference page about HTTP 201 Created. The page itself is served as 200 OK so it can be indexed as HTTP documentation.

The request succeeded and created one or more new resources. The Location header identifies the primary new resource.

Specification

Registered in the IANA HTTP Status Code Registry as Created. Defined in RFC 9110, Section 15.3.2.

What it means

HTTP 201 Created means the server fulfilled the request and created at least one new resource. The Location header points to the primary resource that was created. If there is no Location header, the new resource is the request's target URI, which is what happens with a successful PUT to a new URL.

When to use it

• Return 201 after a POST that creates a resource, such as a new user, order, note, or comment. RFC 9110 says the server SHOULD include a Location header for the new resource.
• Return 201 when a PUT creates a resource at a URL that did not exist before. RFC 9110 requires 201 in this case. A PUT that replaces an existing resource returns 200 or 204.
• Return 202 Accepted instead when the resource will be created later by a background job and does not exist yet.

Headers involved

• Location identifies the primary resource that was created. It can be an absolute URL or a relative reference such as /api/notes/42, which the client resolves against the request URL.
• Content-Type describes the response body. The body usually describes and links to the new resource.
• ETag, when present, is the validator for the new representation. A client can use it with If-Match on its next update. After a PUT, RFC 9110 allows ETag only if the server stored the body exactly as sent.

Examples

JSON API: POST creates a resource

POST /api/notes HTTP/1.1
Host: example.com
Content-Type: application/json

{
  "content": "Read about status codes",
  "important": true
}

HTTP/1.1 201 Created
Location: /api/notes/42
Content-Type: application/json

{
  "id": "42",
  "content": "Read about status codes",
  "important": true
}

PUT to a new URL

PUT /files/report-2026.csv HTTP/1.1
Host: storage.example.com
Content-Type: text/csv

month,total
Jan,120

HTTP/1.1 201 Created
ETag: "e2c4"
Content-Length: 0

Common mistakes

• Returning 200 after creating a resource. The client still works, but it loses the signal that something new exists and where to find it.
• Leaving out Location on a POST. The client then has to dig the new ID out of the body or guess the URL.
• Treating a retried create request as a new create. With idempotency keys, return the original 201 again or a 200 that points to the existing resource, and document which one.

Developer notes

A browser form POST usually ends with a redirect: the server answers 303 See Other or 302 Found and the browser loads a new page. A JavaScript app that sends JSON with fetch() wants 201 instead, because it stays on the same page, reads the new resource from the response body, and updates the UI without another request.

Questions

What does HTTP 201 Created mean?

HTTP 201 means the request succeeded and created a new resource. The Location header, if present, tells the client the URL of that resource.

Is a Location header required with 201?

For POST, RFC 9110 says the server SHOULD send Location for the primary resource created. Without Location, the client treats the request URL as the new resource, which fits a PUT to a new URL.

Should 201 include a response body?

It can. The body usually describes and links to the new resource. Many APIs return the created object so the client does not need a follow-up GET.

What is the difference between 201 and 202?

201 means the resource exists now. 202 means the server accepted the request but has not finished processing it, so the resource may not exist yet.

See also

• 200 OK
• 202 Accepted
• 204 No Content
• 303 See Other
• REST API status code chooser

Header and content rules

What RFC 9110 says about a 201 response, quoted from the RFC.

• No keyword (sender; Location): The 201 definition does not require Location. Location identifies the primary created resource; without it, the target URI does. Table row

  The primary resource created by the request is identified by either a Location header field in the response or, if no Location header field is received, by the target URI. RFC 9110 §15.3.2

• SHOULD (origin server; Location, content): Answer with 201, a Location for the primary resource, and content that describes the request status and refers to the new resource. When: A POST created one or more resources. Table row

  If one or more resources has been created on the origin server as a result of successfully processing a POST request, the origin server SHOULD send a 201 (Created) response containing a Location header field that provides an identifier for the primary resource created (Section 10.2.2) and a representation that describes the status of the request while referring to the new resource(s). RFC 9110 §9.3.3

• MUST (origin server; status): Answer with 201. When: A PUT created a representation where none existed. Table row

  If the target resource does not have a current representation and the PUT successfully creates one, then the origin server MUST inform the user agent by sending a 201 (Created) response. RFC 9110 §9.3.4

The same rules are in the response obligations table and its JSON.

2xx successful – the request was successfully received, understood, and accepted