409Conflict
The request is valid, but it clashes with the current state of the thing it wants to change.
How you get a 409
The client saves an edit it made to version 3 of a document. The database says the document is already at version 4. Applying the edit would overwrite someone else's work, so the app sends 409.
Who sends itApp
- Browser
- CDN
- Proxy
- App
- DB
Typically the application, because only it knows the current state of the data. It usually finds out from the database, through a version check or a uniqueness rule.
In short
What a 409 Conflict means
A 409 Conflict means the request was well formed and allowed, and still cannot be applied, because the thing it targets is not in the state the request assumes. Someone else edited the document first. The email address is already registered. The order has shipped and can no longer be cancelled. The application sends it, usually after the database has reported the clash through a version check or a unique constraint. A 409 is meant for conflicts the client can resolve: the response should say what clashed, so the client can fetch the current state, redo its change on top, and submit again. Blindly resending the same request cannot work, because the state that caused the conflict is still there.
Common causes of a 409
1Two people edited the same record and the second save is based on an old version.
How to check: Compare the version or updated-at value the client sent with the one stored now.
2A unique value already exists: an email address, a username, a slug.
How to check: The database names the rule that refused it.
duplicate key value violates unique constraint "users_email_key"3The action does not fit the current status, such as cancelling an order that has shipped.
How to check: Fetch the resource and read its status before sending the action.
4The same create was submitted twice, by a double click or a retry.
How to check: Look for an identical request a moment earlier that succeeded.
Retry or not?
Retry only after fixing the request · Re-read, then resend
Headers that matter
- ETag
- The version of the resource as it is now. Fetch it before redoing the change.
- If-Match
- Request header: “apply this only if the version is still X”. A server that checks it answers 412, not 409, when it fails.
In the real world
RFC vs real deployments
RFC 9110 describes 409 as a conflict with the resource's current state that the user might be able to resolve, and asks servers to explain the clash in the response. When the version check is done with the If-Match header, the precise code for a failed check is 412 Precondition Failed. Many APIs use 409 for both, and also for duplicates, where some prefer 422.
Seen in a real outage
Conflicts exist because two writers can both be right about what they saw. After a 43-second network cut at GitHub in 2018, two database sites each held writes the other did not have, and reconciling them took a day.
Your turn
Which code is it?
Two colleagues open the same record. Both edit it. The first save succeeds. The second gets 409. What should the second client do?
409 questions
- Who sends a 409 Conflict?
- Typically the application, after the database reports a clash such as a stale version or a value that must be unique and already exists.
- How do I fix a 409?
- Read the response body to see what clashed. Then fetch the current state, redo your change on top of it or choose a different value, and send the new request.
- What is the difference between 409 and 412?
- Both report a state clash. A 412 is specifically the answer when a condition in a request header such as If-Match fails. A 409 is the general case.
Sources: RFC 9110: 409 Conflict (section 15.5.10) ↗ · RFC 9110: If-Match (section 13.1.1) ↗ · Report a problem
Diagrams are our own simulations. All wording is original and paraphrases the linked sources.
Practise this in the DNS / HTTP track
Two-minute animated lessons, then boss fights from real outages. Free, no account needed.