The request conflicts with the current state.
When to use it
Duplicate unique values, or an edit based on a stale version.
Common causes and fixes
409 means the request is valid but clashes with the current state. Typical cases: inserting a duplicate username or email that violates a unique constraint, creating something that already exists, or saving a record someone else changed since you read it, detected by a version column. Map the database’s unique violation (Postgres 23505, MySQL 1062) to 409 instead of letting it surface as a 500.
The body should say what conflicted and ideally include the current version, so the client can merge or ask the user. Retrying unchanged fails again, unless the conflict was transient, such as a lock held by another transaction. Kubernetes returns 409 when an update carries a stale resourceVersion; the fix is the usual loop: read again, reapply the change, resend.
Client error (4xx)
4xx codes are client errors: the request itself is wrong, unauthorised or points at something that isn’t there. Retrying the same request won’t help.
What it looks like
HTTP/1.1 409 ConflictHow to send it
| Node.js / Express | res.status(409).end() |
|---|---|
| Python / Flask | return '', 409 |
| nginx | return 409; |
How to check it
curl -s -o /dev/null -w "%{http_code}\n" https://example.com/