409 Conflict
Request could not be completed due to a conflict with the current state of the resource.
Usually happens because:
- ☑ Attempting to register an email
- ☑ Uploading a file version that
- ☑ Circular dependency creations in system
🔍 Quick Checklist:
Meaning
The HTTP 409 Conflict client error status code indicates a request conflict with the current state of the target resource. Conflicts are most likely to occur in response to a PUT or POST request (e.g. duplicate key inserts in databases).
Root Causes
- Attempting to register an email address that already exists in the database.
- Uploading a file version that conflicts with edits made by another user (edit conflicts).
- Circular dependency creations in system structures.
| Cause | Frequency |
|---|---|
| Attempting to register an email | ⭐⭐⭐⭐⭐ |
| Uploading a file version that | ⭐⭐⭐⭐ |
| Circular dependency creations in system | ⭐⭐⭐ |
Common Mistakes
- Using 400 Bad Request instead of 409 Conflict for duplicate database records.
- Omitting error explanation messages, leaving clients confused about what state triggered the conflict.
How to Fix
Framework-Specific Examples
Checking database records and returning 409 for duplicates.
app.post('/register', async (req, res) => {
const exists = await User.findOne({ username: req.body.username });
if (exists) {
return res.status(409).json({ error: 'Username taken' });
}
});Server Configuration Examples
Nginx passes status 409 downstream.
# 409 handled by applicationPrevention
- Setup transaction isolation rules inside databases.
- Validate user input states before running writing mutations.
Frequently Asked Questions (FAQ)
Q: When should I return a 409 Conflict?
Return 409 when the request is syntactically correct (not a 400), but cannot be completed because it violates business logic constraints (e.g. duplicate username, or mid-air edit collisions).
Q: Is 409 Conflict cacheable?
No. By default, 409 responses are not cacheable, as they represent dynamic transaction blocks.
Q: How do clients resolve 409 conflicts?
The client should fetch the latest resource state, merge changes, and ask the user to re-submit or choose alternative parameters.
Q: How does 409 differ from 412 Precondition Failed?
Use 412 when HTTP conditional check headers (like If-Match) fail. Use 409 for application business logic conflicts (like database constraints).