412 - Precondition Failed
HTTP 412 Precondition Failed means a conditional request precondition evaluated to false on current resource state.
Last reviewed: February 12, 2026|Editorial standard: source-backed technical guidance
What Does Precondition Failed Mean?
The server rejected the operation because the conditional guard did its job: the resource changed or no longer satisfies the client preconditions required for safe update/read.
Common Causes
- -If-Match validator does not match current ETag.
- -If-Unmodified-Since fails because resource changed.
- -Client reuses stale conditional headers in mutation flows.
How to Fix Precondition Failed
- 1Fetch the latest representation and refresh validators (`ETag`, `Last-Modified`) before retrying conditional requests.
- 2Send correct conditional headers (`If-Match`, `If-Unmodified-Since`, `If-None-Match`) based on operation intent.
- 3Handle failed preconditions explicitly in client logic instead of blind retry loops.
Step-by-Step Diagnosis for Precondition Failed
- 1Capture the exact conditional headers and validator values sent on the failing request.
- 2Compare client validators to current origin validators returned by a fresh `GET` or `HEAD`.
- 3Trace concurrent writes or cache staleness that can invalidate preconditions between read and write.
- 4Retest with updated validators and verify client conflict-resolution logic handles 412 deterministically.
Conditional Header and Validator Audit
- -Inspect validator mismatch paths (example: `If-Match: "abc"` while current ETag is `"def"`).
- -Verify correct conditional mode per use case (example: optimistic update needs `If-Match`, cache revalidation needs `If-None-Match`).
Concurrency and Cache Staleness Trace
- -Correlate write events between read and mutate windows (example: another client updates resource 200 ms before your PUT).
- -Audit intermediary cache freshness and revalidation behavior (example: stale edge cache serves old validator to writer client).
Implementation Examples
curl -i -X POST https://api.example.com/v1/resource -H "Content-Type: application/json" -d "{"sample":true}"
# Response:
# HTTP/1.1 412 Precondition Failed
# {"error":"Precondition Failed","code":"412"}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 === 412) {
console.error('Handle 412 Precondition Failed');
}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 == 412:
print('Handle 412 Precondition Failed')How to Verify the Fix
- -Repeat conditional requests and confirm they succeed only when validators are current.
- -Run parallel update tests to ensure stale validators still fail safely with 412.
- -Confirm client retries now refresh validators instead of replaying stale headers.
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
- -return both current ETag and conflict metadata in 412 payloads so clients can auto-refresh and rebase without extra discovery calls.
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.