Fix HTTP 409 Conflict API Errors
HTTP 409 means the request conflicts with the resource's current state. Read the latest state and the API's conflict details before deciding whether to merge, retry, or stop.
Identify the conflict type
Capture the operation, resource identifier, request ID, response error code, current version metadata, and a redacted representation of the attempted change. Common conflicts include a duplicate unique name, stale resource version, invalid state transition, an already completed operation, and reuse of an idempotency key with different input. The status alone does not tell the client which recovery is safe.
Protect updates with versions
For optimistic concurrency, the server can return an ETag or explicit version with a read. The client sends that value in If-Match or the documented version field when updating. If another writer changes the resource first, the server rejects the stale write instead of silently overwriting it. Fetch the current representation and show or apply a deliberate merge.
Resolve uniqueness conflicts
A create request can conflict with an existing username, slug, external ID, or other unique key. Do not rely on a separate availability check because two clients can pass it concurrently. Enforce uniqueness atomically at the data boundary and translate the violation into a stable field-level error. The client can choose another value or retrieve the existing resource when the contract supports that workflow.
Validate state transitions
Actions such as cancel, approve, publish, or refund may only be valid from specific states. Return the current state and allowed next actions without exposing private data. The client should refresh and decide whether the desired outcome already exists. Repeating a transition blindly can create duplicate effects or obscure a race between workers.
Use idempotency for retried writes
Creation and payment APIs often accept an idempotency key. Reusing the same key with the same operation should return the established outcome according to the API contract. Reusing it with different input should be rejected. Scope keys correctly, store them durably, compare an input fingerprint safely, and retain them for the documented retry window.
Retry only after reconciliation
An unchanged automatic retry usually reproduces a 409. Retry only when the client has refreshed state, resolved the merge, chosen a new unique value, or confirmed that transient lock contention is the documented cause. Bound attempts and add jitter for explicitly retryable conflicts. Compare redacted representations with the JSON Diff tool.
Frequently Asked Questions
Should every 409 be retried?
No. Reconcile the conflicting state first.
Can ETags prevent lost updates?
Yes. Use If-Match with the version that was read.
Are duplicate idempotency keys always errors?
No. Behavior depends on whether the repeated input is identical and on the API contract.