Precondition Failed

4xx Client Error

.md

ELI5

You said 'only do this if that thing is true', but that thing turned out to be false, so I didn't do anything.

Server perspective

Use 412 when the client supplied a conditional header and that precondition evaluated to false.

When to use

•Return 412 for failed If-Match, If-Unmodified-Since, or similar explicit request preconditions
•Use it to stop stale writes or invalid conditional operations before they change state
•If-Match header doesn't match current ETag
•If-Unmodified-Since header fails time check
•If-None-Match header matches current ETag
•Conditional updates that fail preconditions

How to respond

•Explain which precondition failed when that helps client recovery
•Keep 412 distinct from 428, which is about a missing required precondition

Headers to consider

•If-Match
•If-None-Match
•If-Unmodified-Since
•If-Modified-Since

Response body

•Optionally include which precondition failed and the current validator when safe to expose.

Server-side pitfalls

•Use 409 for broader state conflicts that are not tied to a specific conditional header
•Do not use 412 when the required precondition header was missing entirely; use 428
•General conflicts (use 409 Conflict)
•Missing preconditions (use 428 Precondition Required)
•Authentication issues (use 401 Unauthorized)

Examples

Conditional update with outdated ETag

Request:

PUT https://api.example.test/api/users/123

# Headers
If-Match: "old-etag"

Response:

412 Precondition Failed

# Headers
Content-Type: application/json

# Body
{
  "error": "precondition_failed"
}

Resource was modified since client last fetched it, ETag no longer matches

References

Related Status Codes

409

Conflict

There's a conflict - what you're trying to do clashes with something that already exists or the current state.

428

Precondition Required

You're trying to change something, but you need to tell me what you expect it to look like first, so we don't accidentally overwrite someone else's changes.

304

Not Modified

You already have the latest version! The thing you're asking for hasn't changed since you last got it.