Conflict

Description

Examples

POST /api/users HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer token123

{"email": "[email protected]", "name": "Alice Smith"}

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

{"error": "conflict", "message": "A user with email [email protected] already exists.", "conflicting_field": "email", "existing_resource": "/api/users/42"}

PUT /api/documents/17 HTTP/1.1
Host: api.example.com
Content-Type: application/json
If-Match: "v3-abc123"

{"title": "Updated Title", "body": "New content..."}

HTTP/1.1 409 Conflict
Content-Type: application/json
ETag: "v4-def456"

{"error": "conflict", "message": "Resource was modified by another request. Your version: v3, current version: v4.", "current_etag": "v4-def456", "your_etag": "v3-abc123", "modified_by": "user/89", "modified_at": "2024-01-15T10:28:00Z"}

POST /api/orders/55/ship HTTP/1.1
Host: api.example.com
Authorization: Bearer admin-token

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

{"error": "invalid_state_transition", "message": "Cannot ship order 55: current state is 'cancelled'. Only orders in state 'paid' can be shipped.", "current_state": "cancelled", "allowed_transitions": ["refund", "archive"]}

Edge Cases

• •409 implies the conflict is RESOLVABLE — always include enough information for the client to fix it (conflicting field, current version, allowed states).
• •For optimistic concurrency: return the current ETag in the 409 response so the client can fetch the latest version, merge, and retry.
• •409 is NOT for validation errors — 'invalid email format' is 422, but 'email already taken' is 409 (it's about resource state, not request validity).
• •Some APIs return 409 for rate limiting or resource locking — technically acceptable if framed as 'resource is in a conflicting state (locked by another process)'.
• •Git push rejection is conceptually a 409 — your branch diverged from the remote. The resolution is to pull, merge, and push again.
• •Database deadlocks that bubble up to the HTTP layer often manifest as 409 — the client can retry after a brief delay.
• •For bulk operations: if one item in a batch conflicts, decide whether to fail the entire batch (409 on the batch endpoint) or return partial success with per-item status.

When You'll See This

• →Duplicate email or username on user registration
• →Optimistic lock failure — another user edited the document between your read and write
• →Git push rejected because remote has diverged
• →Trying to delete a resource that has dependent children (foreign key constraint)
• →State machine violation: publishing an already-archived article
• →Creating a resource with a slug/ID that already exists
• →Concurrent requests trying to claim the same limited resource (ticket, reservation slot)

Implementation References

History

Introduced in HTTP/1.1 (RFC 2068, 1997). Originally envisioned for PUT conflicts where two users edit the same resource simultaneously. Became critical with the rise of RESTful APIs that enforce unique constraints, versioning (ETags), and state machines. The optimistic concurrency pattern (If-Match + ETag + 409 on mismatch) is now a standard pattern in distributed systems.

Related Status Codes

Related Headers

FAQ