What does HTTP status code 409 mean?
The 409 Conflict status code indicates that the request cannot be completed because it conflicts with the current state of a resource (e.g. database constraints).
When to use it in APIs
Use 409 for optimistic concurrency conflicts (stale version tags), duplicate unique keys (like email address collisions), or a retry that arrives while the original request with the same Idempotency-Key is still in flight. A key reused with a different payload is 422, per the idempotency key draft.
How it compares to other codes
- 422 Unprocessable Content: Used for general field-level business validation. 409 is reserved for state-driven conflicts.
