HTTP
409 - Conflict
HTTP 409 Conflict means the request conflicts with the current state of the target resource.
Last reviewed: February 18, 2026|Editorial standard: source-backed technical guidance
What Does Conflict Mean?
The operation is blocked to protect current resource state, so clients must reconcile versions, preconditions, or workflow order before a safe retry.
Common Causes
- -Concurrent writes hit unique index on normalized email value, and second transaction fails conflict check.
- -If-Match or version field is stale after parallel update, so optimistic concurrency guard rejects mutation.
- -Job naming strategy uses minute-level timestamp, so duplicate create requests collide on identical resource ID.
How to Fix Conflict
- 1Fetch the latest resource representation, then retry mutation with current precondition tokens (for example
If-Match/ version fields). - 2Enforce deterministic write ordering and idempotency controls for concurrent mutation flows.
- 3Return actionable conflict details to callers so they can merge state instead of blind-retrying.
Step-by-Step Diagnosis for Conflict
- 1Capture conflict metadata (version, ETag, lock, duplicate key, or workflow state) returned with 409.
- 2Re-read resource state immediately before mutation to detect stale client snapshots.
- 3Trace concurrent writers and sequencing decisions through request IDs and workflow events.
- 4Retest with explicit preconditions and idempotency keys to confirm conflict path is eliminated.
State Version and Preconditions
- -Inspect precondition signals used by the endpoint (example: stale
If-MatchETag conflicts with current document version). - -Verify clients are not caching mutable state too long before writes (example: UI edits based on 10-minute-old snapshot).
Workflow Ordering and Uniqueness Conflicts
- -Trace business-state transitions for invalid order (example: shipping update sent before payment capture reaches final state).
- -Audit uniqueness/idempotency constraints (example: duplicate create uses same external order ID or idempotency key).
Implementation Examples
Reproduce HTTP 409 Conflictcurl
curl -i -X POST https://api.example.com/v1/resource -H "Content-Type: application/json" -d "{"sample":true}"
# Response:
# HTTP/1.1 409 Conflict
# {"error":"Conflict","code":"409"}Handle 409 in JavaScriptjavascript
const response = await fetch('https://api.example.com/v1/resource', {
method: 'POST',
headers: { 'Content-Type': 'application/json', 'Accept': 'application/json' },
body: JSON.stringify({ sample: true })
});
if (response.status === 409) {
console.error('Handle 409 Conflict');
}Handle 409 in Pythonpython
import requests
response = requests.post(
'https://api.example.com/v1/resource',
headers={'Accept': 'application/json', 'Content-Type': 'application/json'},
json={'sample': True}
)
if response.status_code == 409:
print('Handle 409 Conflict')How to Verify the Fix
- -Repeat the mutation and confirm 409 resolves when current preconditions are supplied.
- -Validate concurrency controls across normal, burst, and parallel writer scenarios.
- -Monitor conflict-rate metrics and ensure they drop to expected baseline after rollout.
How to Prevent Recurrence
- -Adopt optimistic concurrency tokens and idempotency guards for mutating operations.
- -Serialize high-contention writes and enforce deterministic dependency ordering.
- -Monitor precondition and lock-related failure signals with actionable alerts.
Pro Tip
- -include machine-readable conflict reasons (for example
version_mismatch,duplicate_external_id) so SDKs can auto-select merge or refresh flows.
Decision Support
Compare Guide
409 Conflict vs 412 Precondition Failed: When to Use Each
Choose 412 when If-Match or If-Unmodified-Since checks fail; choose 409 for state conflicts without failed precondition headers during concurrent updates.
Playbook
Conflict and Concurrency Playbook (409 / 412 / OptimisticLock)
Use this playbook to separate true write conflicts from stale precondition failures, then apply safe re-fetch, optimistic-lock, and retry choices.
Official References
Provider Context
This guidance is specific to HTTP services. Always validate implementation details against official provider documentation before deploying to production.