Conflict
Client Error (4xx)The 409 Conflict status code indicates that the request conflicts with the current state of the target resource. This is commonly used for write conflicts such as trying to create a resource that already exists, concurrent edit conflicts, or version mismatches in optimistic concurrency control. The response should include enough information for the client to resolve the conflict.
What is HTTP 409 Conflict?
HTTP 409 Conflict is a client error (4xx) status code. The 409 Conflict status code indicates that the request conflicts with the current state of the target resource. This is commonly used for write conflicts such as trying to create a resource that already exists, concurrent edit conflicts, or version mismatches in optimistic concurrency control. The response should include enough information for the client to resolve the conflict. Common causes include attempting to create a duplicate resource and concurrent edit conflict (optimistic locking). To fix it, fetch the current version of the resource and merge changes.
Example Response
HTTP/1.1 409 Conflict
Content-Type: application/json
{"error": "Resource already exists", "existingId": 42} Common Causes
- • Attempting to create a duplicate resource
- • Concurrent edit conflict (optimistic locking)
- • Version mismatch in If-Match header
- • Resource state does not allow the requested operation
How to Fix
- 1. Fetch the current version of the resource and merge changes
- 2. Use conditional requests (If-Match) for optimistic concurrency
- 3. Handle duplicate creation with a check-then-create pattern
- 4. Retry with the latest resource version
Frequently Asked Questions
When should I return 409 vs 400?
Use 409 when the request is well-formed but conflicts with the resource's current state (duplicate, version mismatch). Use 400 when the request itself is malformed or invalid.
How does optimistic concurrency use 409?
The client sends an If-Match header with the resource's ETag. If the resource has been modified since the client's last read (ETag mismatch), the server returns 409. The client must fetch the latest version and retry.
Is 409 appropriate for username-already-taken errors?
Yes. If a user tries to register with a username that already exists, 409 Conflict is appropriate because the request conflicts with the existing state of the user database.