HTTP Caching Headers: Cache-Control, ETags, Vary and How CDNs Read Them
Two caching bugs account for most of the pain. The first: you deploy, and half your users keep running last week's JavaScript because something cached app.js for a day. The second is worse: a CDN serves one logged-in user's dashboard to another because the response was cacheable and nobody said otherwise. Both come down to a handful of response headers, and both are avoidable once you know how caches actually read them.
The rules live in RFC 9111 (HTTP Caching, June 2022, which replaced RFC 7234), with validators and Vary defined in RFC 9110. This post sticks to what those say, then looks at how Cloudflare and Fastly bend them. For the higher-level question of what to cache where, our HTTP caching strategies guide is the companion piece.
How a cache decides: key, freshness, age
A cache stores a response under a cache key, which RFC 9111 says is built "from, at a minimum, the request method and target URI". Most caches only store GET responses, so in practice the key is the URL plus whatever Vary adds.
A stored response is fresh while its age is less than its freshness lifetime: response_is_fresh = (freshness_lifetime > current_age). The lifetime comes from s-maxage (shared caches only), then max-age, then Expires. A cache that serves a stored response adds an Age header saying how many seconds old it is, which is the first thing to look at when debugging.
If there's no explicit lifetime at all, caches may guess. RFC 9111 suggests a heuristic of some fraction of the time since Last-Modified, and says "a typical setting of this fraction might be 10%". So a file last modified ten days ago can be treated as fresh for about a day without you ever asking for that. That's the usual cause of the stale app.js bug: no Cache-Control, a Last-Modified header, and a cache doing exactly what the spec allows. Always send explicit Cache-Control.
The Cache-Control directives you'll actually use
| Directive | What it means (RFC 9111) |
|---|---|
max-age=N | Fresh for N seconds in any cache |
s-maxage=N | Overrides max-age and Expires in shared caches only (CDNs, proxies) |
no-cache | May be stored, but must be revalidated with the origin before every reuse |
no-store | Don't store any part of the request or response |
private | Shared caches must not store it; the browser may |
public | Cacheable even where it otherwise wouldn't be, e.g. a request with Authorization |
must-revalidate | Once stale, don't reuse without revalidating; if the origin is unreachable, return an error (typically 504) |
immutable | Won't change while fresh, so don't revalidate on reload (RFC 8246) |
The one everyone gets wrong: no-cache does not mean "don't cache". MDN puts it plainly: it "allows caches to store a response but requires them to revalidate it before reuse." If you mean "never store this", that's no-store.
Four recipes that cover most sites
# 1. Fingerprinted static assets: /assets/app.3f9a1c.js
Cache-Control: public, max-age=31536000, immutable
# 2. HTML documents and other entry points
Cache-Control: no-cache
ETag: "v42-9b2c"
# 3. Per-user API responses
Cache-Control: private, no-cache
# 4. Anything sensitive (tokens, account pages, payment flows)
Cache-Control: no-store
Recipe 1 only works with cache-busting filenames: when the content changes, the URL changes. MDN's example uses exactly this pair, max-age=31536000, immutable, for hashed assets. Recipe 2 is what makes recipe 1 safe: the HTML is always revalidated, so it always points at the current asset URLs, and revalidation is cheap thanks to the ETag. Recipe 3 lets the browser store a copy and revalidate it, but keeps shared caches out of it entirely.
If you want a CDN to hold something longer than browsers, add s-maxage: Cache-Control: public, max-age=60, s-maxage=3600. Then purge the CDN on deploy, because browsers will still hold their 60-second copy.
Validation: ETag, Last-Modified and 304
Revalidation is how a cache asks "is my copy still good?" without downloading the body again. The origin sends a validator with the original response, and the cache sends it back on the next request:
$ curl -sI https://example.com/report
HTTP/2 200
cache-control: no-cache
etag: "a1b2c3"
last-modified: Wed, 04 Nov 2026 09:12:00 GMT
$ curl -sI https://example.com/report -H 'If-None-Match: "a1b2c3"'
HTTP/2 304
cache-control: no-cache
etag: "a1b2c3"
A few rules from RFC 9110 that matter when you implement this yourself:
- Weak vs strong.
ETag: W/"xyzzy"is weak: it may stay the same across changes the origin considers equivalent, and should change whenever old copies stop being acceptable substitutes. ForIf-None-Match, a recipient "MUST use the weak comparison function", soW/"a1"and"a1"match. - ETag beats date. If a request carries both, the server "MUST ignore If-Modified-Since";
If-None-Matchis considered the more accurate check. - What a 304 must include. Any of
Content-Location,Date,ETag,Vary,Cache-ControlandExpiresthat a200would have carried. ForgettingCache-Controlon the304is a classic way to reset an object's lifetime by accident.
Generate ETags from something cheap and stable: a content hash, or a row's updated_at plus its id. Hashing a 2 MB response on every request to save sending it is a trade worth measuring.
Vary: the header that splits the cache
Vary lists the request headers that change the response, and a cache may only reuse a stored response when those headers match the new request. Vary: Accept-Encoding is the common, harmless one. Problems start elsewhere:
- Missing Vary. If you choose the response by
Accept-Language, a cookie or an API-version header and don't list it, a shared cache will serve one variant to everyone. - Too much Vary.
Vary: User-Agentsplits the cache into thousands of near-identical copies and your hit rate drops off a cliff. Vary: *. RFC 9111 says a stored response with*"always fails to match", which makes it effectively uncacheable for reuse.
When the variant really depends on the user, the answer is usually private, not a clever Vary.
Serving stale on purpose
RFC 5861 (Informational, May 2010) adds two extensions that make caches more forgiving:
stale-while-revalidate=N: after the response goes stale, a cache may keep serving it for up to N seconds while it revalidates in the background.stale-if-error=N: if revalidation hits a500,502,503or504, the cache may serve the stale copy for up to N seconds past expiry.
The RFC's own example is max-age=600, stale-while-revalidate=30: fresh for ten minutes, then a 30-second grace window. A request has to arrive inside that window to trigger the background refresh, so on low-traffic URLs some visitors will still wait for a full revalidation.
What CDNs do differently
Spec-compliant doesn't mean identical. A few behaviours worth knowing, from the vendors' docs as of November 2026:
Cloudflare
- Out of the box it caches by file extension, and it "does not cache HTML or JSON by default". It also won't cache a response with
Set-Cookie, or a request that isn'tGET. - With no caching headers, default edge TTLs are 120 minutes for
200,206and301, 20 minutes for302and303, and 3 minutes for404and410. - In its Cache-Control docs,
stale-while-revalidateis fully asynchronous,stale-if-erroronly kicks in on 5xx,immutable"has no effect on public caches like Cloudflare", ands-maxagedisablesstale-while-revalidate. Several directives (no-cache,max-age=0,must-revalidate) behave differently depending on the Origin Cache Control setting, so check which mode your zone runs in.
Fastly
- TTL precedence is
Surrogate-Control: max-age, thens-maxage, thenmax-age, thenExpires; with none of them, the default is 2 minutes. Surrogate-Controlis stripped before the response reaches the browser, so it's a clean way to give the edge its own TTL.s-maxageis not stripped.stale-while-revalidateandstale-if-errordefault to 0, and responses withSet-Cookieorprivatearen't cached by default.
The standard way to target CDNs
RFC 9213 (June 2022) defines CDN-Cache-Control, which uses the same directives but only applies to CDNs. When it's present, a CDN that honours it ignores Cache-Control for its own decision. Cloudflare supports it and passes it downstream, and also accepts Cloudflare-CDN-Cache-Control, which only Cloudflare reads.
Cache-Control: no-cache
CDN-Cache-Control: max-age=300, stale-while-revalidate=60
That combination keeps browsers revalidating every time while the edge holds a five-minute copy. If you're choosing a CDN in the first place, our Cloudflare vs CloudFront comparison covers the wider differences.
Debugging checklist
When something is cached that shouldn't be, or isn't when it should be:
curl -sIthe URL twice and compareAge,ETagand any cache-status header your CDN adds. An increasingAgemeans a shared cache is serving it.- Read the full
Cache-Controlline, includingprivate,no-storeands-maxage. Our HTTP header parser puts each header from a raw block on its own row, though it doesn't splitCache-Controlinto directives. - Look for
Set-Cookieon responses you expected to be cached at the edge; both Cloudflare and Fastly skip them by default. - Check
Varyagainst what the response really depends on. - Send
If-None-Matchwith the current ETag and confirm a304that repeatsCache-ControlandETag. - Check whether the CDN has its own rules or a targeted header overriding the origin.
- If it's slow rather than stale, split the request into DNS, connect, TLS and time to first byte; our HTTP timing analyzer shows which phase dominates.
And the one-line rule to take away: hashed assets get immutable, HTML gets no-cache plus an ETag, per-user data gets private, and secrets get no-store.
Written by AIDToolStack Editorial
Researched from official documentation, specifications and vendor pages, listed under Sources below. Last checked November 2026.
Sources
- www.rfc-editor.org/rfc/rfc9111.html
- www.rfc-editor.org/rfc/rfc9110
- www.rfc-editor.org/rfc/rfc5861.html
- www.rfc-editor.org/rfc/rfc8246.html
- www.rfc-editor.org/rfc/rfc9213.html
- developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Cache-Control
- developers.cloudflare.com/cache/concepts/default-cache-behavior/
- developers.cloudflare.com/cache/concepts/cache-control/
- developers.cloudflare.com/cache/concepts/cdn-cache-control/
- www.fastly.com/documentation/guides/concepts/edge-state/cache/cache-freshness/
Related Posts
Explore on AIDToolStack
Discover tools and servers featured in our directory.
AI Tools
MCP Servers
Sponsor Our Newsletter
Reach thousands of developers who are actively evaluating AI tools, MCP servers, and dev infrastructure. Our weekly newsletter goes to engaged technical decision-makers.
All sponsored content is clearly labeled per our editorial policy.