409 Conflict

Description

The 409 Conflict status code indicates that the request could not be completed due to a conflict with the current state of the target resource. This status code is used when a request conflicts with the current state of the server or would cause a conflict in the resource being modified.

This status code is commonly used when: - A client attempts to create a resource that already exists - A client attempts to update a resource that has been modified by another client since it was last retrieved - A client attempts to delete a resource that is referenced by other resources - A client attempts to perform an operation that would violate data integrity constraints

The 409 Conflict status helps maintain data integrity by preventing operations that would result in an inconsistent state. The response should include enough information for the client to recognize and resolve the conflict.

Syntax

The server responds with a 409 Conflict status and includes information about the conflict:

HTTP/1.1 409 Conflict
Content-Type: application/json
Content-Length: [length in bytes]

{
  "error": "Conflict",
  "message": "The request could not be completed due to a conflict with the current state of the resource",
  "details": [specific information about the conflict]
}

Examples

Resource Already Exists Example

A client attempts to create a resource with an identifier that already exists:

Client Request:

POST /api/users HTTP/1.1
Host: api.example.com
Content-Type: application/json
Content-Length: 85

{
  "username": "johndoe",
  "email": "[email protected]",
  "name": "John Doe"
}

Server Response:

HTTP/1.1 409 Conflict
Content-Type: application/json
Content-Length: 144

{
  "error": "Conflict",
  "message": "User with username 'johndoe' already exists",
  "suggestion": "Try a different username or use the existing account"
}

Concurrent Modification Example

A client attempts to update a resource that has been modified since it was last retrieved:

Client Request:

PUT /api/documents/123 HTTP/1.1
Host: docs.example.com
Content-Type: application/json
If-Match: "a7f8d2e4c6b9"
Content-Length: 253

{
  "title": "Updated Document Title",
  "content": "This is the updated content of the document.",
  "author": "Jane Smith"
}

Server Response:

HTTP/1.1 409 Conflict
Content-Type: application/json
ETag: "e1f2a3b4c5d6"
Content-Length: 215

{
  "error": "Conflict",
  "message": "The document has been modified since you last retrieved it",
  "current_version": "e1f2a3b4c5d6",
  "your_version": "a7f8d2e4c6b9",
  "suggestion": "Retrieve the current version and merge your changes"
}

Data Integrity Constraint Example

A client attempts to delete a resource that is referenced by other resources:

Client Request:

DELETE /api/categories/42 HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Server Response:

HTTP/1.1 409 Conflict
Content-Type: application/json
Content-Length: 243

{
  "error": "Conflict",
  "message": "Cannot delete category that contains products",
  "details": {
    "category_id": 42,
    "product_count": 15,
    "product_ids": [101, 102, 103, 104, 105, "..."]
  },
  "suggestion": "Remove or reassign all products before deleting this category"
}

Summary

The 409 Conflict status code is an important tool for maintaining data integrity in web applications and APIs. It provides a clear indication to clients that their request would result in a conflict with the current state of the resource or system. By including detailed information about the nature of the conflict and potential resolutions, servers can guide clients toward resolving the issue appropriately. This status code is particularly valuable in collaborative environments, concurrent editing scenarios, and systems with complex data relationships where preventing conflicting operations is essential.