HTTP Status Code 409 Conflict is a response status code that indicates a request could not be completed due to a conflict with the current state of the target resource. This status code is typically used when the requested operation cannot be performed on the resource because it would violate some constraint or business rule.
When to use 409 Conflict
The 409 Conflict status code should be used when a request cannot be completed due to a conflict in the current state of the resource. This may occur when:
- A client tries to create a resource that already exists
- A client tries to update a resource with a version that is out-of-date
- A client attempts to delete a resource that has dependencies
In these cases, the server should provide enough information for the user to resolve the conflict, such as including a description of the conflict in the response body or providing a link to a resource that can help the user understand and resolve the issue.
How to handle 409 Conflict
When a client receives a 409 Conflict status code, it should take the following steps to resolve the issue:
- Examine the response body for information about the conflict.
- Determine if the conflict can be resolved by the client. If so, modify the request and resubmit it.
- If the conflict cannot be resolved by the client, notify the user and provide them with the information needed to resolve the issue.
Example request and response
Request
In this example, a client attempts to create a new user with an email address that already exists in the system.
POST /users HTTP/1.1
Host: example.com
Content-Type: application/json
{
"email": "johndoe@example.com",
"password": "mypassword"
}Response
The server responds with a 409 Conflict status code, indicating that the user cannot be created because the email address is already in use.
HTTP/1.1 409 Conflict
Content-Type: application/json
{
"error": "Conflict",
"message": "A user with the provided email address already exists."
}In this case, the client should notify the user of the conflict and provide them with the information needed to resolve the issue, such as suggesting that they log in with their existing account or use a different email address.
Summary
The 409 Conflict status code is used to indicate that a request cannot be completed due to a conflict with the current state of the resource. When a client encounters a 409 Conflict, it should examine the response body for information about the conflict, determine if it can be resolved, and take the appropriate action to resolve the issue.
