428 - Precondition Required

Start Here

Use the closest compare guide, playbook, or adjacent error page to narrow the decision faster before you start changing production systems.

This page is part of the Error Reference library. Learn more about the project or report a correction.

What Does Precondition Required Mean?

The origin refuses unconditional mutations and requires preconditions so concurrent updates do not silently overwrite newer resource state.

Common Causes

• -Update route requires If-Match for concurrency control, and clients omitting header are rejected consistently.
• -Gateway policy enforces conditional DELETE headers for shared resources to prevent accidental destructive updates.
• -Sync worker retries stale writes without refreshing ETag, so server demands explicit precondition header.

How to Fix Precondition Required

1. 1Fetch current resource validators (for example ETag) and send conditional headers on every mutation.
2. 2Implement optimistic concurrency logic in clients to retry only after state refresh.
3. 3Reject unconditional write paths in SDKs so missing preconditions are caught before network send.

Step-by-Step Diagnosis for Precondition Required

1. 1Capture failing mutation request and confirm required conditional headers are absent or invalid.
2. 2Inspect origin policy that mandates conditional writes and its documented validator requirements.
3. 3Trace client write paths to identify callers bypassing ETag/version fetch before mutate.
4. 4Retest with correct preconditions and verify lost-update protection remains intact.

curl -i -X PUT https://api.example.com/v1/resource/42 -H "Content-Type: application/json" -d "{"status":"approved"}"
# Response:
# HTTP/1.1 428 Precondition Required
# {"error":"Precondition Required","code":"428"}

const response = await fetch('https://api.example.com/v1/resource/42', {
  method: 'PUT',
  headers: { 'Accept': 'application/json', 'Content-Type': 'application/json' },
  body: JSON.stringify({ status: 'approved' })
});
if (response.status === 428) {
  console.error('Handle 428 Precondition Required');
}

import requests

response = requests.put(
    'https://api.example.com/v1/resource/42',
    headers={'Accept': 'application/json', 'Content-Type': 'application/json'},
    json={'status': 'approved'}
)
if response.status_code == 428:
    print('Handle 428 Precondition Required')

Seen in Production

Debugging Tools

• -ETag/validator inspection via HEAD/GET traces
• -Write-path middleware logs for conditional header injection
• -Concurrency simulation tests
• -Audit logs for blocked unconditional mutations

How to Verify the Fix

• -Repeat mutations with valid preconditions and confirm 428 is cleared for compliant requests.
• -Run concurrent update tests to ensure unconditional requests are still blocked intentionally.
• -Validate conflict-resolution UX and retry flow for stale validator cases.

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

Related Errors

Official References

• -RFC 6585 Section 3 - 428 Precondition Required definition
• -IANA HTTP Status Code Registry - 428 Precondition Required
• -MDN Web Docs — 428 Precondition Required
• -HTTP Official Documentation