This article is also maintained as a reference guide at JsonMind.
A cache bets that a stored response will still be acceptable when the next request arrives. HTTP splits that bet into freshness (reuse without asking the origin) and validation (refresh a stale copy cheaply). Nearly every caching bug is a mistake in one of those decisions. The contract is enforced by systems you do not control — browser, proxy, CDN, service worker — so a wrong header rarely fails in staging; it surfaces as a customer seeing another customer's invoice or an API serving data from before a password change.
Freshness and validation: the two questions every cache answers
Freshness is a lifetime, not a flag. The origin grants it with Cache-Control: max-age=N in seconds, s-maxage=N for shared caches only, or Expires as an absolute date. A cache tracks age from the origin's Date and the Age added by intermediaries, then reuses the response only while it is below the freshness lifetime. s-maxage overrides max-age in a CDN; Cache-Control overrides Expires.
Validation is a comparison. Once an entry is stale, the cache sends If-None-Match with the stored ETag, or If-Modified-Since with the stored Last-Modified. A 304 Not Modified refreshes the entry without a body; a 200 replaces it. With no validator, the full response is downloaded again.
Both failure directions hurt: a lifetime that is too long serves replaced or private content, while a lifetime of zero adds a round trip without guaranteeing freshness. A correct policy names each resource class — hashed asset, HTML, public JSON, authenticated JSON, error — and assigns it an explicit mechanism.
Cache-Control directives that change behavior
Four distinctions explain most incidents. no-cache means store but revalidate before every reuse, not "do not cache." no-store means do not write the response to disk or memory at all. private lets the browser store it but forbids shared caches. public makes it storable by shared caches even when it would otherwise be refused, so it must never appear on authenticated data.
The stale-serving directives buy resilience during outages. stale-while-revalidate=N lets a cache serve stale for up to N seconds while it refreshes in the background; stale-if-error=N extends that window when revalidation fails with a 5xx or network error. Both are defined in RFC 5861, widely supported, and capable of hiding origin failures: enable them deliberately and monitor the origin.
| Directive | Applies to | What it does | Common mistake |
|---|---|---|---|
max-age=N |
every cache | fresh for N seconds | expecting a change to invalidate immediately |
s-maxage=N |
shared caches | overrides max-age in CDNs and proxies |
assuming browsers honor it |
no-cache |
every cache | may store, must revalidate before reuse | reading it as "do not store" |
no-store |
every cache | must not store any part of the response | using private where tokens are involved |
private |
shared caches | only the browser may store it | expecting it to prevent browser storage |
public |
shared caches | storable even with Authorization
|
adding it to authenticated responses |
must-revalidate |
every cache | no stale reuse after expiry | omitting it on data that cannot be stale |
stale-while-revalidate=N |
every cache | serves stale while refreshing in the background | enabling it without a validator |
stale-if-error=N |
every cache | serves stale when the origin fails | masking a prolonged outage |
immutable |
browsers | skips revalidation while fresh | using it on unversioned URLs |
A public marketing page can combine browser revalidation with a short shared lifetime:
HTTP/1.1 200 OK
Date: Tue, 17 Nov 2026 08:00:00 GMT
Content-Type: text/html; charset=utf-8
Cache-Control: public, max-age=0, s-maxage=60, stale-while-revalidate=300
ETag: "7c3a1f9d9b2e"
Vary: Accept-Encoding
Age: 37
Browsers treat the document as stale immediately and revalidate; the CDN serves it fresh for 60 seconds and may serve a stale copy for another 300 seconds while revalidating. Age: 37 says the copy is 37 seconds old, which is the number to watch when a deploy seems slow. The HTTP headers analyzer parses a captured response and shows which directives a specific layer added.
ETag, weak validators, and the 304 response
An ETag is an opaque validator chosen by the origin: a hash of the representation bytes, or a version identifier that changes with them. A process-local counter or file modification time breaks on multiple nodes, because each node produces a different value and conditional requests bounce between 304 and 200.
Strong ETags compare byte for byte; weak ETags, written W/"...", promise only semantic equivalence, enough for If-None-Match but not for range requests or If-Range. If-None-Match uses weak comparison even for strong tags and takes precedence over If-Modified-Since. That combination is the right default: ETag first, date as a fallback.
A 304 is not an empty success. It must not carry a body, should repeat ETag, Cache-Control, Date, and Vary, and updates the stored metadata: a cache receiving a new max-age on 304 must adopt it. Last-Modified has one-second resolution, so two edits in the same second look identical; keep it at least one second older than Date or heuristic caches may refuse to store the response.
Vary, cache keys, and normalization
Vary lists the request headers that were part of the response's identity. If the body changes with Accept-Encoding, the response must say Vary: Accept-Encoding; otherwise a CDN can hand a Brotli body to a client that only advertised gzip, and the user sees corrupted text. The same applies to Accept-Language and any custom negotiation header.
Vary is also a performance switch. Vary: User-Agent creates a variant per user agent string and shreds the hit ratio. Vary: Cookie creates a variant per cookie value, which usually means no shared caching at all, and it is not a security boundary: sloppy key normalization can still collide. Vary: * marks the response as unreusable without revalidation. Prefer a cookie-free host for static assets and keep personalized responses out of shared caches.
Cache keys are not only the URL. CDNs normalize query order, strip tracking parameters, lowercase the host, and sometimes ignore the scheme or a trailing slash. If that normalization differs from the origin's interpretation, two resources share one key — the mechanism behind cache poisoning and cache deception. Document the key for each route, confirm it includes every input that changes the body, and test with parameters in different orders.
Shared caches, CDNs, Age, and clock skew
A private cache belongs to one user; a shared cache serves many. RFC 9111 forbids a shared cache from reusing a stored response to a request with Authorization unless the response carries public, s-maxage, or must-revalidate. That is a floor, not a recommendation: authenticated responses should normally carry private or no-store.
Set-Cookie deserves its own warning. Its presence does not prevent a shared cache from storing the response, so a CDN can cache a page that sets a session cookie and replay that header to other users. Strip Set-Cookie at the edge or mark the response private.
Age and Date report time. Apparent age is roughly the cache's receive time minus Date, plus the Age it received. Clock skew corrupts that estimate: a fast origin clock triggers early revalidation, a slow one keeps responses fresh too long. Keep nodes on NTP and treat Age as the truth for how long a copy has existed.
Without an explicit expiration, caches may apply heuristic freshness, commonly 10% of the interval since Last-Modified. That is why an unconfigured static file can be cached for hours and an unconfigured API response for minutes. Heuristics are a guess; explicit Cache-Control is a decision. Check x-cache, cf-cache-status, or x-served-by to see which layer answered and whether it was a hit, a revalidation, or a bypass.
Hashed assets, HTML, and safe deployment
Hashed assets and HTML need opposite policies. app.9f2c1a.css gets a new URL whenever its bytes change, so it can be cached for a year: Cache-Control: public, max-age=31536000, immutable. immutable tells browsers to skip even a reload revalidation while fresh, removing a conditional request from every page load. The guarantee depends on the URL changing with the content; immutable on an unversioned path is a cache you cannot clear.
HTML names those hashed URLs, so it must be revalidated frequently: Cache-Control: no-cache plus a strong ETag, or a short shared TTL such as s-maxage=60, stale-while-revalidate=300. Long-lived HTML is the classic deploy failure: the browser keeps an old document that references bundles the new release deleted, and users get 404s until they hard-refresh.
Deployments should be atomic in the cache's terms. Upload new hashed assets before the HTML that references them, keep the previous release available for at least one cache lifetime, and only then remove it. Fonts and CSS imported by old bundles need the same grace period, and a rollback must still find its assets.
Invalidation, purge, and versioned URLs
Purging only reaches caches you control, and that set is smaller than you think. A CDN purge API clears edge copies by URL, tag, surrogate key, or wildcard; propagation takes seconds to minutes across points of presence. It does not clear browser caches, corporate proxies, or service worker storage. Users who already hold a copy keep it until their TTL expires or they revalidate.
Changing Cache-Control does not purge anything. The new header applies to the next fetch; existing copies keep their old lifetime. Teams routinely "fix" a stale asset by editing headers, redeploy, and see no change because no cache re-fetched the object.
Versioned URLs are the only invalidation mechanism that works across every cache. Change the URL when the content changes, and old copies become irrelevant rather than wrong. Use purge for mistakes and for content that cannot change its URL: a pricing page, an image with a fixed path, a legal document. Prefer tag-based purge over URL lists because a page and its fragments change together, and treat wildcard purges as an outage risk: they can empty a CDN and send every user to the origin at once. A 301 can be cached indefinitely, so temporary moves need 302 or 307 with a short lifetime.
Tokens, PII, and no-store
Anything that identifies a user, grants access, or carries personal data belongs outside every shared cache, and usually outside the browser's disk cache too. A response to an authenticated request should carry Cache-Control: no-store. private prevents CDN storage but still lets the browser keep the body on disk, the wrong default for a bearer token, a one-time download link, or an account profile.
Vary: Authorization is not a substitute. It fragments the cache by credential, still stores every variant, and a cache that mishandles the key can serve one user's response to another. Set-Cookie is not a substitute either. The safe pattern is explicit: no-store on the response, no caching of 401 and 403 bodies that echo request details, and a CDN rule that bypasses authenticated paths rather than trusting origin headers alone.
Apply the same rule to errors. A 500 page with a stack trace, an email address, or an internal hostname should never be stored by a shared cache; no-store on errors costs nothing and prevents a small incident from becoming a data exposure. The back-forward cache is separate from HTTP caching but also keeps rendered pages in memory, so logout should invalidate server-side sessions rather than rely on headers.
Verification checklist with concrete pass criteria
Verify from the outside, in the same order a request travels. Start with curl against production, not a local server with caching disabled:
# 1. Inspect the headers a CDN actually returns
curl -sSI https://www.example.com/pricing | grep -iE '^(HTTP/|cache-control:|etag:|vary:|age:|date:)'
# 2. Capture the ETag, then ask for the same URL conditionally
etag=$(curl -sSI https://www.example.com/pricing | awk -F': ' 'tolower($1)=="etag"{print $2}' | tr -d '\r')
curl -sS -o /dev/null -w 'status=%{http_code} bytes=%{size_download}\n' \
-H "If-None-Match: $etag" https://www.example.com/pricing
# 3. Compare the variants a cache must keep apart
curl -sSI -H 'Accept-Encoding: gzip' https://www.example.com/app.js | grep -i '^vary:'
curl -sSI -H 'Accept-Encoding: br' https://www.example.com/app.js | grep -i '^vary:'
Then repeat the requests in browser DevTools with "Disable cache" off. That checkbox makes the browser send Cache-Control: no-cache on every request, so a freshness bug disappears while it is enabled. Read the Size column for "from disk cache" or "from memory cache", and use the Timing panel to confirm that no round trip occurred. The HTTP request workbench reproduces a request with exact headers, and the cURL converter turns a copied browser request into an equivalent command.
Treat a check as passed only when all of the following hold:
| Check | How to test | Pass criteria |
|---|---|---|
| Hashed asset | Two requests for the same hashed URL |
Cache-Control: public, max-age=31536000, immutable; second response is a hit with a larger Age
|
| HTML revalidation | Conditional GET with the stored ETag |
304, zero-byte body, same ETag, refreshed Cache-Control
|
| Authenticated JSON | Request with a real session cookie |
Cache-Control: no-store, no Age, CDN status BYPASS or DYNAMIC
|
| Compression variants | Same URL with Accept-Encoding: gzip and br
|
Vary: Accept-Encoding present and both bodies decode correctly |
| CDN hit behavior | Repeated requests through one point of presence |
x-cache: HIT or cf-cache-status: HIT with Age below the configured TTL |
| Deploy consistency | Load the site immediately after a release | HTML references new hashed URLs and every referenced asset returns 200
|
Failure modes and production rules
The expensive failures are predictable:
- A long
max-ageon HTML pins an old document that references deleted bundles. - A missing
Vary: Accept-Encodingserves the wrong compression to the wrong client. -
no-cacheis read asno-store, so tokens or personal data land on disk. -
privateis used whereno-storeis required, leaving a token in the browser cache. - ETags generated per process or from file mtimes cause
200/304ping-pong across nodes. - A CDN purge leaves every browser copy untouched, so support keeps hearing about stale pages.
- A
5xxor a personalized404is cached and replayed to other users. -
immutableis applied to a URL whose bytes can change. -
Expiresin the past fightsCache-Controland confuses older proxies. -
Vary: User-AgentorVary: Cookiedestroys the hit ratio while providing no safety.
The rules that prevent them are short. Default to no-store for anything authenticated or personalized, and opt into caching explicitly per route. Put Vary next to the code that performs content negotiation, not in a global config someone forgets. Give hashed assets a year and immutable, give HTML no-cache and a validator, and give public JSON a short s-maxage with stale-while-revalidate. Version URLs for invalidation, use purge only for mistakes, and monitor Age, hit ratio, and origin traffic after every deploy. Verify with curl and DevTools: a CDN dashboard reports what the edge believes, not what the user received.
If you want to inspect a real response, the HTTP Headers Analyzer parses Cache-Control, ETag, Vary, and Age, and the HTTP Request Workbench lets you replay conditional requests without installing anything.
Top comments (0)