409 Status Code: Meaning, Usage, and Examples in REST APIs

The 409 Conflict status code indicates that the request could not be completed because it conflicts with the current state of the resource. It is used when a client tries to make a change that would cause a conflict, such as editing a resource that was updated elsewhere.

How It Works

Imagine you and a friend are trying to edit the same document at the same time. If you both try to save different changes simultaneously, the system needs a way to prevent one person's work from accidentally overwriting the other's. In web APIs, the 409 Conflict status code acts like a warning sign that tells the client, "Your request can't be completed because it conflicts with the current state of the resource."

This means the server has detected a conflict, such as trying to update or create a resource that already exists or has been changed by someone else. The client should then resolve the conflict, often by fetching the latest version of the resource and retrying the request.

Example

This example shows a simple REST API endpoint in Python using Flask that returns a 409 Conflict status when a user tries to create a resource that already exists.

python

from flask import Flask, request, jsonify

app = Flask(__name__)

# Simulated database of usernames
users = {"alice", "bob"}

@app.route('/users', methods=['POST'])
def create_user():
    data = request.get_json()
    username = data.get('username')
    if username in users:
        return jsonify({"error": "User already exists."}), 409
    users.add(username)
    return jsonify({"message": f"User {username} created."}), 201

if __name__ == '__main__':
    app.run(debug=True)

Output

When POSTing {"username": "alice"} to /users, response status: 409 Conflict with message {"error": "User already exists."}

When to Use

Use the 409 Conflict status code when a client's request cannot be processed because it would cause a conflict with the current state of the resource. Common scenarios include:

• Trying to create a resource that already exists (e.g., duplicate username or ID).
• Attempting to update a resource that has been modified by someone else since the client last fetched it (optimistic concurrency control).
• Conflicting edits or operations that violate business rules.

This status helps clients understand that they need to resolve the conflict before retrying, often by refreshing their data or changing their request.

Key Points

• 409 Conflict means the request conflicts with the current resource state.
• It prevents accidental overwrites or duplicates.
• Clients should handle this by resolving conflicts, like fetching updated data.
• Common in APIs that support concurrent edits or unique resource constraints.

Key Takeaways

409 Conflict signals a request conflicts with the current resource state.

Use 409 to prevent duplicate or conflicting resource changes.

Clients should resolve conflicts before retrying the request.

It is common in APIs with concurrent edits or unique constraints.