HTTP 409 field note
API 409 Conflict: state collision, duplicate key, or idempotency misuse
Diagnose API 409 responses caused by stale versions, duplicate resources, in-flight operations, or reused idempotency keys.
A conflict is usually about current state, not malformed syntax. Record the resource version, operation identifier, idempotency key, and concurrent request history before retrying. Repeating the same write can intensify the conflict if the operation is not designed for replay.
Treat the complete response as an evidence record: status, headers, provider code, request identifier, method, and raw body. The sequence below separates what the response proves from the checks still needed before a safe retry or code change.
Diagnostic procedure
Work from evidence to recovery.
- 01
Identify the contested state
Look for resource IDs, version or ETag values, unique fields, and in-progress operation IDs in the error body.
- 02
Choose merge, replace, or wait
A stale version requires a fresh read; an in-flight mutation may require serialization; a duplicate may require returning the existing resource.
- 03
Do not rotate keys blindly
A new idempotency key can turn one intended operation into a second side effect. First establish whether the original request executed.
POST /payments Idempotency-Key: order-42 409 key used with different parameters
Fetch operation order-42 → compare payload fingerprint → resume or return stored result
Duplicate-side-effect riskPOST retries can repeat side effects. Add an idempotency key or a durable operation identifier before enabling automatic retries.
No account · no upload · no endpoint calledOpen the full retry planner and operating notes →
FAQ
Before you ship
Does APITC send this evidence to an API?
No. The matching and calculations in the linked workbench run in the active browser tab.
Should every 409 response be retried?
No. Retry behavior depends on the method, idempotency protection, provider instructions, and whether the failure is temporary.
Protocol behavior checked against the MDN — 409 Conflict. Recheck your pinned provider/API version before production deployment.