409 Conflict

The request is well-formed but collides with current state: a duplicate unique key, a stale version in optimistic locking, or an operation invalid in the resource's present status. The client should refetch state, reconcile, and retry deliberately — not blindly.

What usually causes it

  • Creating something that already exists (unique constraint)
  • Optimistic-concurrency version/ETag mismatch (someone edited first)
  • State-machine violations (shipping an already-cancelled order)

How to debug and fix it

  1. On create-conflicts, decide idempotency policy: return the existing resource, or surface the duplicate to the user.
  2. On version conflicts, refetch, merge or prompt the user, and retry with the fresh version/ETag.
  3. Never auto-retry a 409 unchanged — by definition, the same request will conflict again.

Easily confused with

Debugging an API? Build and inspect requests, check response headers, or read the full status-code debugging guide.