Built by Abstract: powerful API's for every use case.
Learn more 🚀

HTTP Status Code
409 - Conflict

4xx Client errors

The HTTP Status Code 409 means that the client's request could not be processed because of conflict in the current state of the resource.

What is HTTP Status Code 409?

HTTP status codes, such as the HTTP Status Code 409, are essential parts of any web developer's toolkit. According to rfc7231 section 6.5.8, this specific status code is defined as "Conflict" and is part of the HTTP/1.1 standard.

HTTP Status Code 409 is a server response status code indicating that the request could not be completed due to a conflict with the current state of the target resource. This status code is usually returned when the requested update or modification to a resource could not be completed because it would create a conflict in the system's state.

More Than a Status Code

Beyond being an HTTP status symbol, the status code represents a communication tool between the client and server. The server uses this HTTP status constant to indicate a problem with the HTTP request, and the client can then take appropriate action to resolve the conflict.

HTTP 409 vs. HTTP 400

It's important to note the difference between HTTP Status Code 409 and a 400 "Bad Request" status code. A "Bad Request" generally indicates that the server was unable to understand the request due to invalid syntax, while a 409 status code implies that the server understood the request, but refuses to fulfill it due to a conflict in the current state of the resource.

When and How is HTTP Status Code 409 used?

Typical Usage Scenario

The HTTP Status Code 409 is used whenever there is a conflict in the current state of a resource that prevents the server from fulfilling the request. In a typical scenario, a client sends an HTTP request to modify a resource on the server. If another client has already modified the same resource since the first client last retrieved it, the server will respond with a 409 status code. This is an instance of a request conflict, and the HTTP status constant 409 is used to indicate this.

Representation in Different Languages

Different programming languages and frameworks have their own ways of representing this status code. For example, in Rails, the HTTP status symbol for a 409 conflict is `:conflict`. In Python2, the HTTP status constant is `httplib.CONFLICT`, and in Symfony, the HTTP status constant is `Response::HTTP_CONFLICT`.

Conflict Resolution and Error Messages

When a 409 status code is returned, the server should also include an error message in the response body that describes the nature of the conflict, thus providing the client with information useful for resolving it. This error message is also often referred to as a conflict response.

For instance, in a version control system, the error message might detail the conflicting changes and their revision history, enabling the user to resolve the conflict manually. Furthermore, in a RESTful API context, a PUT request method to a target resource might result in a 409 status code if the requested resource has been updated since the client last fetched it, and the server is unable to merge the changes automatically.

Understanding and effectively using HTTP Status Code 409 can significantly enhance the reliability and robustness of your applications. As developers, we should be familiar with status codes and their implications to ensure smooth communication between clients and servers and to handle potential request conflicts efficiently.

Example usage of HTTP Status Code 409

A Simple Analogy of Status 409

Imagine you and a colleague are collaborating on a document. You both download the current version and start making different changes. When you try to upload your version, your colleague has already uploaded their changes. You receive a message that there's a conflict because the document has been updated since you last downloaded it. This situation is akin to an HTTP 409 Conflict status code, which indicates a request conflict with the current state of the target resource.

A More Technical Example

Consider an API for a version control system like Git. A client makes a PUT request to update a file with their changes. However, someone else has already pushed changes to the same file. The server can't merge these changes automatically, and thus, it responds with a 409 Conflict status code. Here's a simplified version of what that could look like in code:

@app.route('/files/', methods=['PUT'])
def update_file(filename):
    uploaded_file = request.get_file()
    if file_has_changed_since(uploaded_file.last_modified):
        abort(409)  # Conflict
        return '', 204  # No Content

What is the history of HTTP Status Code 409?

The HTTP 409 Conflict status code is part of HTTP/1.1, defined in RFC 2616 in 1999 and refined in RFC 7231 in 2014. It's used to indicate that a request cannot be completed due to the current state of the target resource. This status code is commonly associated with PUT requests, where the intent is to replace the state of the target resource. If the current state of the resource prevents the server from fulfilling the request, a 409 Conflict status code is appropriate. However, it's important to note that a PUT request can have side effects on other resources, which might result in a 409 Conflict status as well.

How does HTTP Status Code 409 relate to other status codes?

HTTP status codes are categorized into five classes: informational responses (100-199), successful responses (200-299), redirection messages (300-399), client error responses (400-499), and server error responses (500-599). HTTP 409 Conflict belongs to the client error responses class.

It's similar to the 400 Bad Request status code, which indicates that the server cannot or will not process the request due to an apparent client error. But unlike 400, a 409 response is specific to conflict in the current state of the resource.

It differs from 404 Not Found and 410 Gone status codes. While 409 Conflict indicates a conflict in the current state of the resource, 404 and 410 indicate that the requested resource could not be found or is no longer available, respectively.

A 409 Conflict can also be seen as an alternative to 415 Unsupported Media Type. If a PUT representation is inconsistent with the target resource, the server can respond with a 409 Conflict or a 415 Unsupported Media Type status code. The latter is specific to constraints on Content-Type values.

Please note that this is a simplified comparison and the use of status codes may vary based on the specific constraints of a given application or API.

Other interesting things about HTTP Status Code 409

The HTTP 409 Conflict status code, while not the most common one you might encounter, plays a vital role in RESTful APIs and the HTTP protocol as a whole. Here are a few interesting facts about this status code.

1. 409 is about Concurrency Control: The 409 Conflict status code plays a significant role in maintaining the integrity of resources in concurrent operations. It's a crucial part of HTTP's built-in concurrency control mechanism, allowing for safer and more effective collaboration and simultaneous updates.

2. 409 and Idempotency: HTTP methods like PUT and DELETE are idempotent, meaning multiple identical requests should have the same effect as a single request. But, if a client makes two identical PUT requests, and another client modifies the resource in between, the second PUT request from the first client could result in a 409 Conflict. This is a fascinating aspect of how idempotency and HTTP 409 Conflict status code intersect.

3. It’s not just about PUT: While 409 Conflict is often associated with PUT requests, it's not exclusive to them. It can be used in response to other HTTP methods if the request cannot be completed due to the current state of the resource.

4. 409 and Error Handling: A server responding with a 409 Conflict status code should also provide enough information to help the client resolve the conflict. This could include a list of current resource conflicts or the differences between the client's request and the current resource state. This demonstrates how HTTP status codes like 409 contribute to robust and transparent error handling in APIs.

5. Influence on Caching: Responses to the PUT method, which may often elicit a 409 Conflict status, are not cacheable. If a successful PUT request passes through a cache that has stored responses for the request URI, those stored responses will be invalidated.

These intriguing facets of HTTP 409 Conflict highlight its nuanced role within HTTP operations, contributing to the protocol's flexibility and robustness.

Additional Links and Codes Related to Status Code 409

Written by Benjamin Bouchet.
Last updated May 31, 2023.