HTTP 428 Precondition Required: meaning and fixes
Meaning
HTTP 428 Precondition Required means a write must include a condition such as If-Match. Fetch the current ETag before retrying.
HTTP 428 means the origin requires a conditional request: “Precondition Required”. RFC 6585 section 3 defines it for resources that want clients to use a precondition such as If-Match before a write. The purpose is to prevent a client from overwriting a newer representation it never read.
428 is different from 412. A 428 says the required condition was missing. A 412 says a condition was supplied but evaluated false. A proxy can relay either response, but the condition belongs to the origin resource and should survive a change of proxy address.
Reproduce an ETag precondition
This Python 3.15.0 server keeps a document and changes its ETag after each successful PUT:
import hashlib
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
doc = {"body": b'{"title": "draft one"}\n'}
def etag():
return '"' + hashlib.sha256(doc["body"]).hexdigest()[:12] + '"'
class H(BaseHTTPRequestHandler):
protocol_version = "HTTP/1.1"
def reply(self, code, body=b"", extra=()):
self.send_response(code)
for key, value in extra:
self.send_header(key, value)
self.send_header("Content-Length", str(len(body)))
self.end_headers()
self.wfile.write(body)
def do_GET(self):
self.reply(200, doc["body"], [("ETag", etag())])
def do_PUT(self):
new = self.rfile.read(int(self.headers.get("Content-Length", 0)))
sent = self.headers.get("If-Match")
if sent is None:
return self.reply(428, b'This request is required to be conditional; try using "If-Match".\n')
if sent != etag():
return self.reply(412, b"ETag has changed; GET the resource again.\n")
doc["body"] = new
self.reply(204, extra=[("ETag", etag())])
ThreadingHTTPServer(("127.0.0.1", 47428), H).serve_forever()
$ curl -si -X PUT --data '{"title":"draft two"}' http://127.0.0.1:47428/doc
HTTP/1.1 428 Precondition Required
Server: BaseHTTP Python/3.15.0
Content-Type: text/plain
Content-Length: 66
This request is required to be conditional; try using "If-Match".
$ ETAG=$(curl -s -o /dev/null -w "%header{etag}" http://127.0.0.1:47428/doc)
$ curl -s -o /dev/null -w "%{http_code} new etag %{header{etag}}\n" -X PUT -H "If-Match: $ETAG" --data '{"title":"draft two"}' http://127.0.0.1:47428/doc
204 new etag "bbd9956b020a"
$ curl -s -w "%{http_code}\n" -X PUT -H "If-Match: $ETAG" --data '{"title":"draft three"}' http://127.0.0.1:47428/doc
412
The capture used curl 8.7.1 and the standard library. The second write used a current tag and succeeded; reusing that old tag produced 412. Through Squid 6.13, the same request without If-Match returned 428 and a fresh conditional request returned 204. The proxy did not create the precondition.
What to change in a client
GET the representation, save its ETag, apply your change locally and send If-Match: "tag" with the write. If the server returns 412, GET again and merge the newer representation. An If-None-Match header has different semantics and can be wrong for an update. curl’s --etag-compare option is designed for cache validation, not for inventing an If-Match update token.
A scraper normally sees 428 only when it is writing or calling an API that requires an idempotency or version header. A proxy that strips conditional headers can turn a valid request into 428, so compare the headers at the origin when you control the path. Do not send a stale tag forever or rotate addresses to escape the conflict.
If-Match with an idempotency key if the API documents one. A conditional request prevents an old representation from overwriting new data, but it cannot tell you whether a timed-out write was already committed.Causes and fixes
| Cause | Response | Fix |
|---|---|---|
| PUT or PATCH has no precondition | 428 and a body names If-Match or another condition | GET the resource and send the required header |
| ETag is stale | 412 after a conditional write | Fetch the current representation, merge and retry once |
| Wrong conditional header | 428 persists after using If-None-Match on an update | Follow the API contract and use the header it requires |
| Proxy strips the condition | Direct write succeeds, proxied write gets 428 | Inspect proxy header policy and preserve If-Match |
| Client copied an ETag from another URL | 412 on every write to the target | Read the target’s own ETag before the write |
See HTTP 412 for failed conditions and Retry-After for a different kind of retry signal. The curl proxy guide shows how to compare direct and proxied conditional headers. A 428 is a request-shape problem, not a proxy reputation signal.
A custom API may also require an idempotency key, but that is application policy rather than a standard HTTP precondition. Treat the response body and API documentation as the authority, preserve the conditional header through every proxy hop, and fetch a fresh representation after a 412.