What it means
A duplicate that violates a uniqueness constraint, or an optimistic-concurrency failure where someone else edited the record first. The body should say what conflicted - 409 alone leaves the client with no next step.
- Class
- 4xx Client error
- Defined in
- RFC 9110 §15.5.10
- Cached by default
- No
When you receive a 409
- Something in the current state blocks the request - a duplicate key, or a newer version saved by someone else.
- Read the body for what conflicted, fetch the current state, and retry against it.
- Resending the same request unchanged will usually conflict again.
When you send a 409
- For a uniqueness violation, or a stale version in an optimistic-locking update. When the client sent
If-Match,412is the exact code. - Say what conflicted and, where you can, the current version.
- For a value that is wrong on its own, regardless of state,
422fits.
On the wire
HTTP/1.1 409 Conflict
Content-Type: application/json
{"error": "version_conflict", "detail": "The order was changed by another request", "currentVersion": 7}