The successful HTTP response codes for a PUT request are 200 OK, 201 Created, and 204 No Content, each indicating a distinct positive outcome for the operation.
A PUT request is fundamental for managing resources on the web, primarily used to update an existing resource or create a new one if it doesn't already exist at the specified Uniform Resource Identifier (URI). Understanding the appropriate success code helps clients accurately interpret the server's response and manage their state accordingly.
Understanding PUT Requests
The HTTP PUT method is an idempotent operation, meaning that making the same request multiple times will have the same effect as making it once. It's typically used to replace an existing resource with new data or to create a resource at a specific URI if one doesn't already exist. The entire payload provided in the request body is considered the new state of the resource.
Key Successful PUT Response Codes
When a PUT request is processed successfully, the server can respond with one of several HTTP status codes, each conveying specific information about the outcome. The 200, 201, and 204 HTTP status codes are widely considered "Success" results for PUT operations.
200 OK: General Success
The 200 OK status code is the most common and versatile success code. For a PUT request, it signifies that the resource at the target URI was successfully updated or replaced with the content provided in the request body.
- When to Use: This code is ideal when the server has successfully modified an existing resource, and the response body might contain a representation of the updated resource, a status message, or other relevant information.
- Example: A client updates a user's profile. The server responds with
200 OKand includes the updated user object in the response body.
201 Created: Resource Creation or Replacement
The 201 Created status code indicates that the request has been fulfilled and has resulted in one or more new resources being created. While often associated with POST requests, PUT can also lead to a 201 Created response if the request successfully created a resource that did not previously exist at the specified URI. It can also be used if an existing resource was completely replaced and the server considers this a new "creation" in a logical sense.
- When to Use:
- When a PUT request successfully creates a new resource because the URI specified did not point to an existing resource.
- The response should include a
Locationheader with the URI of the newly created (or re-created) resource and a representation of the resource in the response body.
- Important Note: While
201 Createdis a valid success code for PUT, especially when a resource is newly created, it's worth noting that some existing HTTP integrations or systems might explicitly look for a201 Createdstatus in response to a PUT (Update) request. Developers should be mindful of this, as using200 OKor204 No Contentfor updates is also perfectly valid and widely accepted, and generally should not impact current integrations. - Example: A client uses PUT to specify a new document at
/documents/new-report.pdf. If this document didn't exist, the server creates it and responds with201 Created, including theLocationheader for/documents/new-report.pdf.
204 No Content: Success with No Response Body
The 204 No Content status code signifies that the server successfully processed the request, but is not returning any content in the response body. This is particularly efficient when the client doesn't need to know the state of the updated resource, only that the operation was successful.
- When to Use: This code is appropriate when an existing resource has been successfully updated, and the client application doesn't require a representation of the modified resource or any other data back from the server.
- Example: A client updates a user's status to "online." The server confirms the update with
204 No Contentbecause the client simply needed confirmation that the status was changed, not a full representation of the user object.
Choosing the Right Success Code for PUT
The choice of successful response code for a PUT request depends on the specific outcome and what information the client needs:
- If a new resource was created:
201 Createdis the most semantically correct choice, ideally with aLocationheader. - If an existing resource was updated and the client needs the updated resource representation or a confirmation message:
200 OKis appropriate. - If an existing resource was updated and the client does not need a response body:
204 No Contentis the most efficient choice.
Summary of PUT Success Codes
The following table provides a quick reference for successful PUT response codes:
| HTTP Status Code | Name | Description | When to Use for PUT |
|---|---|---|---|
| 200 | OK | The request has succeeded. | Resource was successfully updated, and the server returns a representation of the updated resource or confirmation. |
| 201 | Created | The request has been fulfilled and has resulted in one or more new resources being created. | A new resource was created at the specified URI, or an existing one was fully replaced and considered "created." |
| 204 | No Content | The server successfully processed the request, and is not returning any content. | An existing resource was successfully updated, and no response body is needed by the client. |
Best Practices for PUT Responses
- Consistency: Maintain a consistent response strategy across your API for similar operations.
- Location Header with 201: Always include a
Locationheader with the URI of the newly created resource when responding with201 Created. - Idempotency: Remember that PUT is idempotent. Multiple identical PUT requests should produce the same outcome (e.g., the resource is updated to the same state), even if the response codes might vary (e.g.,
201for the first creation,200or204for subsequent updates to the same resource). - Informative Bodies (200 OK): For
200 OKresponses, providing a concise response body, often with the updated resource, can be highly beneficial for client applications.
For more detailed information on HTTP status codes, refer to reputable sources such as MDN Web Docs on HTTP Status Codes.
