409 Conflict: State Conflicts and Optimistic Locking
Common Causes of 409 Conflicts
| Cause | Example | How to Fix |
|---|---|---|
| Optimistic locking failure | PUT request with If-Match header using an outdated ETag. | GET the latest version, merge changes, and retry with new ETag. |
| Duplicate resource creation | POST to create a user with an email that already exists. | Inform the client; they must choose a different identifier or update the existing resource. |
| State transition conflict | Trying to cancel an order that is already shipped. | Check the current state and only allow valid transitions. |
| Concurrent edits | Two clients editing the same document simultaneously. | Use a merge strategy or reject the second edit with 409. |
| Dependency conflicts | Deleting a parent resource that has child resources. | Either delete children first or allow cascading deletes. |
Example: Optimistic Locking with ETag
A client attempts to update a resource, but the server detects that the resource has been modified since the client last fetched it:
The client should GET the latest version, merge its changes, and retry with the new ETag.
409 vs. 412 Precondition Failed
- 412 Precondition Failed – the server does not meet the client's preconditions (e.g.,
If-Matchfails). The server returns 412 before attempting to apply the request. - 409 Conflict – the server attempted the request but encountered a conflict with the current state. The conflict may be resolved by the client (e.g., by fetching the latest state and retrying).
In practice, 409 is more common in optimistic locking scenarios because it gives the client more context about the conflict.
When to Use 409
- PUT or PATCH – when the client sends an update based on a stale version.
- POST – when the client tries to create a resource that already exists (duplicate key).
- DELETE – when the resource cannot be deleted because it's referenced by other resources.
- State transitions – when the current state of the resource does not allow the requested operation.
How to Handle 409 on the Client
- Retrieve the current state of the resource (e.g., GET the latest version).
- Inspect the conflict information returned in the response body (if available).
- Merge your changes with the latest state, resolving any conflicts.
- Resend the request with an updated
If-Matchheader or modified payload.
For duplicate creation, inform the user and suggest they use a different identifier or update the existing resource.
Frequently Asked Questions
Is 409 Conflict a client error or a server error?
It's a client error (4xx), because the client's request is based on an outdated state. The server is functioning correctly; it's the client that needs to adapt.
Can 409 be used for validation errors?
No, 409 is for state conflicts, not validation. For validation errors (e.g., invalid email format, missing required field), use 422 Unprocessable Entity.
Should I retry automatically on a 409?
Only if you can resolve the conflict automatically (e.g., by merging changes). If a human decision is required, you should inform the user and let them decide how to proceed.