HTTP
412 - Precondition Failed
HTTP 412 Precondition Failed means a conditional request precondition evaluated to false on current resource state.
Last reviewed: March 10, 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 header carries outdated ETag and conditional update fails after another writer modified entity state.
- -If-Unmodified-Since value is older than latest artifact timestamp, so server denies write to prevent overwrite.
- -Object copy precondition references stale checksum metadata and storage layer rejects operation with precondition failed.
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
GETorHEAD. - 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 needsIf-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
Reproduce HTTP 412 Precondition Failedcurl
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"}Handle 412 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 === 412) {
console.error('Handle 412 Precondition Failed');
}Handle 412 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 == 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.