Precondition Required

4xx Client Error

ELI5

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.

Server perspective

Use 428 when the server requires the request to be conditional, usually to prevent lost updates.

When to use

•Return 428 when clients must send validators such as If-Match before updating a resource
•Use it in optimistic concurrency flows where blind overwrites are not allowed
•Updates require conditional headers for safety
•Preventing lost update problems
•Enforcing optimistic concurrency control
•When If-Match or similar headers are mandatory

How to respond

•Tell the client which precondition header is required, such as If-Match
•Document the fetch-edit-update flow so clients know how to obtain the needed validator

Headers to consider

•No status-specific header is required; identify the required conditional header in the response body or API documentation.

Response body

•Include the required precondition pattern, such as If-Match with the latest ETag.

Server-side pitfalls

•Use 412 when the client sent a precondition and it failed
•Do not leave the client guessing which validator or concurrency pattern is required
•Precondition provided but failed (use 412 Precondition Failed)
•General conflicts (use 409 Conflict)
•Read-only operations that don't need conditions

Examples

Update without precondition header

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

Response:

428 Precondition Required

# Headers
Content-Type: application/json

# Body
{
  "error": "precondition_required"
}

Server requires If-Match header to prevent concurrent updates

References

Related Status Codes

412

Precondition Failed

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

409

Conflict

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