HTTP Response Code for POST When Resource Exists

The most appropriate HTTP response code when a POST request attempts to create a resource that already exists is 409 Conflict. This status code indicates that the request could not be completed due to a conflict with the current state of the target resource. In your case, when a client tries to POST an object with an ID that already exists in your system, the server should return a 409 status to clearly communicate that the resource creation failed because the resource already exists.

Contents

• Understanding the POST Method and Resource Creation
• Recommended Response: 409 Conflict
• Alternative Response Codes
• RFC 7231 Specifications
• Practical Implementation Considerations
• Best Practices for Your API Design
• Response Body and Headers for 409 Conflict

Understanding the POST Method and Resource Creation

The HTTP POST method is defined in RFC 7231 as a method that “requests that the target resource process the representation enclosed in the request according to the resource’s own specific semantics.” POST can be used for various purposes including:

• Creating a new resource when the server assigns the URI
• Appending data to an existing resource
• Processing data without necessarily creating a new resource

In your API design, clients are providing the complete object representation including the ID in the POST request body to /objects/. This differs from the typical use case where POST creates resources without specifying the ID, which is then assigned by the server.

Recommended Response: 409 Conflict

409 Conflict is widely regarded as the most appropriate response code for POST requests that attempt to create resources that already exist. This status code is specifically designed to indicate:

409 Conflict
The request could not be completed due to a conflict with the current state of the target resource. This code is used in situations where the user might be able to resolve the conflict and resubmit the request.

As mentioned in the Stack Overflow discussion, 409 Conflict is the suitable response when:

• The request is trying to create a resource that already exists
• The conflict is due to a violation of uniqueness constraints
• The client needs to be informed about the existing resource

The HTTP status code guide confirms that 409 is the most appropriate approach, and it recommends including the conflicted resource’s URL in the Location header along with a descriptive error message in the response body.

Alternative Response Codes

While 409 Conflict is the primary recommendation, several other status codes could be considered depending on your specific API design choices:

303 See Other

According to RFC 7231, a 303 See Other “MAY be used if the result of processing a POST would be equivalent to a representation of an existing resource.” This could be appropriate if:

• You want to redirect the client to the existing resource
• The POST operation would effectively retrieve an existing resource rather than create a new one

200 OK or 204 No Content

If you decide to treat conflicting POST requests as modification operations rather than errors, you could return:

• 200 OK: If the update was successful and you want to return the updated resource
• 204 No Content: If the update was successful but you don’t want to return any content

This approach treats POST as an “upsert” operation, but it deviates from RESTful principles since POST is not meant to be idempotent.

422 Unprocessable Entity

Some developers suggest using 422 for validation errors, including when a resource already exists. However, this is less common for this specific scenario and typically reserved for semantic validation errors rather than conflicts with existing resources.

RFC 7231 Specifications

RFC 7231 provides the authoritative specification for HTTP semantics. While it doesn’t explicitly address the “resource already exists” scenario for POST, it defines the semantics of the relevant status codes:

409 Conflict: “The request could not be completed due to a conflict with the current state of the target resource. This code is used in situations where the user might be able to resolve the conflict and resubmit the request.”

201 Created: “The request has been fulfilled and has resulted in one or more new resources being created.”

The specification notes that “RFC 7231 (HTTP 1.1) does not require you to always create a resource; an idempotent POST is therefore a valid solution, too” according to one discussion.

Practical Implementation Considerations

When implementing the 409 Conflict response in your API, consider these practical aspects:

Conflict Detection

You need to implement logic to detect when an object with the requested ID already exists. This typically involves:

1. Extracting the object ID from the request body
2. Checking if an object with that ID already exists in your storage
3. Returning 409 if a conflict is detected

Client-Friendly Error Messages

Provide clear error messages that help developers understand what went wrong:

{
  "error": "Conflict",
  "message": "An object with ID '123' already exists",
  "existing_resource": "/objects/123"
}

Idempotency Considerations

If you want to make your POST operations idempotent, you could implement:

• Client-provided timestamps or version numbers
• Server-side deduplication logic
• Conditional requests using ETags or If-Match headers

Best Practices for Your API Design

Given your specific use case where clients provide object IDs, here are some best practices:

1. Be Consistent with PUT Behavior

Since you already have PUT endpoints for creating/modifying objects by ID, consider whether POST should behave differently:

PUT /objects/{id} - Always updates/creates the object with the specified ID
POST /objects/ - Creates a new object with server-assigned ID (recommended)

2. Consider Using POST for Server-Assigned IDs

The RESTful approach would be to use POST for creating resources when the server assigns the ID, and PUT for creating/updating resources when the client specifies the ID.

3. Provide Clear Documentation

Document your API behavior clearly:

• What happens when POSTing an existing object
• What the client should do when they receive a 409 response
• How to check if an object exists before creation

4. Consider Conditional Requests

Implement conditional request support to allow clients to check if a resource exists before attempting creation:

HEAD /objects/{id} - Check if object exists
GET /objects/{id} - Retrieve object if it exists

Response Body and Headers for 409 Conflict

When returning a 409 Conflict response, include appropriate headers and body content:

Recommended Headers

HTTP/1.1 409 Conflict
Content-Type: application/json
Location: /objects/{existing-id}

Recommended Response Body

{
  "error": "Conflict",
  "error_code": "RESOURCE_EXISTS",
  "message": "An object with the specified ID already exists",
  "existing_resource": "/objects/{existing-id}",
  "suggestion": "Use PUT to update the existing resource or check if the object already exists before creating"
}

This response provides the client with:

• Clear indication of the error type
• The specific resource that caused the conflict
• Suggestions for resolving the conflict
• A reference to the existing resource (via Location header)

Sources

1. HTTP response code for POST when resource already exists - Stack Overflow
2. Which HTTP response code for “This email is already registered”? - Stack Overflow
3. What is standard HTTP error code when a resource already exists? - Google Groups
4. RESTful POST request, If the record already exists on POST data - Stack Overflow
5. HTTP response code when resource creation POST fails due to existing matching resource - Stack Overflow
6. RFC 7231 - Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content
7. HTTP Status Code for POST Request When Resource Already Exists - CopyProgramming

Conclusion

Based on REST API best practices and HTTP specifications, 409 Conflict is the most appropriate response code when a POST request attempts to create a resource that already exists. This approach:

• Clearly communicates the conflict to the client
• Follows HTTP semantics as defined in RFC 7231
• Provides clients with actionable information to resolve the issue
• Maintains consistency with RESTful design principles

For your specific API design, consider whether you want to:

1. Use 409 Conflict and treat POST as a creation-only operation
2. Implement upsert behavior (return 200/204 for updates)
3. Modify your API to use POST only for server-assigned IDs and PUT for client-specified IDs

The key is to document your chosen behavior clearly and consistently across all your API endpoints to ensure developers understand how to interact with your service effectively.