201 vs 200 Status Codes: Key Differences

HTTP 200 OK means the request succeeded, while HTTP 201 Created means the request succeeded and created one or more new resources. Use 201 only when creation is the result; otherwise, a successful request will often use 200 or another success status code.

HTTP 200 and 201 at a Glance

An HTTP status code is a three-digit number that tells a client how the server handled a request. Both 200 and 201 belong to the 2xx class, which communicates successful handling.

• 200 OK: The request succeeded. The response content, if any, depends on the request method and what the server returns.
• 201 Created: The request succeeded and resulted in one or more new resources being created before the response was sent.

The practical distinction in a 201 vs 200 status code decision is creation. A successful operation that reads, updates, calculates, searches, or performs an action without creating a resource does not qualify for 201 merely because it succeeded.

When Should an API Use HTTP 200 OK?

Use HTTP 200 OK when the request has succeeded and the result does not need to communicate that a new resource was created. Common cases include retrieving a representation, returning the result of an operation, or confirming an update while including a response representation.

• A GET request successfully retrieves the current representation of a resource.
• A POST request submits data for processing and returns the processing result without creating a new resource.
• A PUT or PATCH request changes an existing resource and returns a representation or other result.
• An action-style request completes successfully and returns information about its outcome.

The meaning of content in a 200 response varies by request method. For example, content returned after GET represents the selected resource, while content returned after POST represents the status of, or results produced by, the action. A response to HEAD uses the same status semantics as GET but does not include response content.

When Should an API Use HTTP 201 Created?

Use HTTP 201 Created when the request has been fulfilled and has caused one or more new resources to exist before the response is sent. Creation must be the actual outcome, not merely the client’s intention.

The server should identify the primary resource that was created. The Location header can contain a reference for that resource. If there is no Location header, the primary created resource is identified by the request target.

A 201 response may include content describing the status of the request and referring to the new resource or resources. The HTTP specification does not require every 201 response to use one fixed body format, so clients should rely on the documented representation format rather than assume a particular JSON structure.

1. Confirm that the operation completed successfully.
2. Confirm that at least one new resource was created before the response was sent.
3. Identify the primary created resource through Location or, when Location is absent, the request target.
4. Return useful response content when the application’s interface defines it.

Should a POST Request Return 200 or 201?

A POST request does not automatically require HTTP 201. The correct choice depends on what happened after the server processed the request.

• Return 201 when POST successfully creates one or more resources.
• Return 200 when POST succeeds, does not create a resource, and returns content describing the result.
• Consider 204 No Content when the action succeeds and there is no response content to send.
• Consider 202 Accepted when processing has been accepted but has not finished.

For example, a POST that sends input to a calculation operation may return 200 with the calculated result. A POST that creates a new record may return 201 and identify the created record. If creation fails, the response should not be 201.

This outcome-based test resolves most status code 201 vs 200 questions: ask whether a new resource now exists because the completed request created it.

What Headers and Bodies Belong in 200 and 201 Responses?

A 200 response may contain a representation of the requested resource, the result of an action, or information about an updated resource. The exact meaning depends on the request method. Some responses, including responses to HEAD, do not carry content even when their status is 200.

A 201 response may contain a representation that describes the result and refers to the newly created resource. When the server sends a Location header, it identifies a specific resource associated with the response. For 201, Location identifies the primary resource created by the request.

• Do not assume that every 200 response has the same body structure.
• Do not assume that every 201 response must repeat the complete created resource.
• Use Location when the primary created resource should be identified separately from the request target.
• Document the response media type and fields so clients know how to interpret the content.

What Are the Most Common 200 and 201 Mistakes?

The most common mistake is choosing a status from the HTTP method alone. POST can produce 200, 201, 202, 204, or an error response because its result depends on what the server actually did.

Another mistake is returning 200 for every successful operation. That removes the useful signal that a resource was created. The opposite mistake is returning 201 when the server only updated an existing resource, started unfinished work, or processed input without creating anything.

Use this concise decision checklist:

1. Did the request finish successfully? If not, do not use 200 or 201 merely to carry an error message in the body.
2. Did the completed request create one or more new resources? If yes, use 201.
3. If no resource was created, does the response return a successful result or representation? If yes, 200 is often appropriate.
4. Did processing only begin but not finish? Consider 202 instead of 201.
5. Is the operation complete with no content to return? Consider 204 instead of an empty 200 where its semantics fit.
6. For 201, can the client identify the primary created resource through Location or the request target?