Skip to content
Tutorials

HTTP Caching Headers: Cache-Control, ETags, Vary and How CDNs Read Them

AIDToolStack EditorialUpdated November 7, 20268 min read
http cachingcdncache-controletagweb development
Share:Twitter

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

DirectiveWhat it means (RFC 9111)
max-age=NFresh for N seconds in any cache
s-maxage=NOverrides max-age and Expires in shared caches only (CDNs, proxies)
no-cacheMay be stored, but must be revalidated with the origin before every reuse
no-storeDon't store any part of the request or response
privateShared caches must not store it; the browser may
publicCacheable even where it otherwise wouldn't be, e.g. a request with Authorization
must-revalidateOnce stale, don't reuse without revalidating; if the origin is unreachable, return an error (typically 504)
immutableWon'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. For If-None-Match, a recipient "MUST use the weak comparison function", so W/"a1" and "a1" match.
  • ETag beats date. If a request carries both, the server "MUST ignore If-Modified-Since"; If-None-Match is considered the more accurate check.
  • What a 304 must include. Any of Content-Location, Date, ETag, Vary, Cache-Control and Expires that a 200 would have carried. Forgetting Cache-Control on the 304 is 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-Agent splits 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 a 500, 502, 503 or 504, the cache may serve the stale copy for up to N seconds past expiry.
Timeline: fresh for 600 seconds, a 30-second stale-while-revalidate window, and stale-if-error coverage until 1800 seconds
Timeline: fresh for 600 seconds, a 30-second stale-while-revalidate window, and stale-if-error coverage until 1800 seconds

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't GET.
  • With no caching headers, default edge TTLs are 120 minutes for 200, 206 and 301, 20 minutes for 302 and 303, and 3 minutes for 404 and 410.
  • In its Cache-Control docs, stale-while-revalidate is fully asynchronous, stale-if-error only kicks in on 5xx, immutable "has no effect on public caches like Cloudflare", and s-maxage disables stale-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, then s-maxage, then max-age, then Expires; with none of them, the default is 2 minutes.
  • Surrogate-Control is stripped before the response reaches the browser, so it's a clean way to give the edge its own TTL. s-maxage is not stripped.
  • stale-while-revalidate and stale-if-error default to 0, and responses with Set-Cookie or private aren'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:

  1. curl -sI the URL twice and compare Age, ETag and any cache-status header your CDN adds. An increasing Age means a shared cache is serving it.
  2. Read the full Cache-Control line, including private, no-store and s-maxage. Our HTTP header parser puts each header from a raw block on its own row, though it doesn't split Cache-Control into directives.
  3. Look for Set-Cookie on responses you expected to be cached at the edge; both Cloudflare and Fastly skip them by default.
  4. Check Vary against what the response really depends on.
  5. Send If-None-Match with the current ETag and confirm a 304 that repeats Cache-Control and ETag.
  6. Check whether the CDN has its own rules or a targeted header overriding the origin.
  7. 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.

AE

Written by AIDToolStack Editorial

Researched from official documentation, specifications and vendor pages, listed under Sources below. Last checked November 2026.

Sources

  1. www.rfc-editor.org/rfc/rfc9111.html
  2. www.rfc-editor.org/rfc/rfc9110
  3. www.rfc-editor.org/rfc/rfc5861.html
  4. www.rfc-editor.org/rfc/rfc8246.html
  5. www.rfc-editor.org/rfc/rfc9213.html
  6. developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Cache-Control
  7. developers.cloudflare.com/cache/concepts/default-cache-behavior/
  8. developers.cloudflare.com/cache/concepts/cache-control/
  9. developers.cloudflare.com/cache/concepts/cdn-cache-control/
  10. www.fastly.com/documentation/guides/concepts/edge-state/cache/cache-freshness/

Related Posts

Explore on AIDToolStack

Discover tools and servers featured in our directory.

MCP Servers

Trigger.dev Jobs MCP ServerManage Trigger.dev background jobs from your AI coding assistant. Monitor job runs, trigger tasks manually, inspect execution logs, manage schedules, and debug failed runs. The server provides operational visibility into your background job infrastructure — see which tasks are running, queued, or failed, and take action. Your AI can help diagnose job failures from execution logs, retry failed tasks, and optimize concurrency configurations for better throughput.Tailscale Network MCP ServerManage your Tailscale mesh VPN network from your AI coding assistant. View connected devices, manage ACLs, configure exit nodes, check device status, and manage DNS settings. The server provides visibility into your Tailscale network — see which machines are online, troubleshoot connectivity issues, manage network access policies, and configure routes. Useful for developers managing distributed infrastructure where Tailscale provides secure networking between services.Portainer Docker MCP ServerManage Docker environments through Portainer's API from your AI coding assistant. Control containers, images, networks, and volumes across multiple Docker hosts and Kubernetes clusters. The server provides tools for container lifecycle management, image pulling and building, stack deployment, and resource monitoring. Portainer's multi-environment management makes this server particularly valuable for teams managing containers across development, staging, and production environments.

Reviews

Sign in to leave a review.

No reviews yet. Be the first!

Comments

Sign in to leave a comment.

No comments yet. Be the first!

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.

Growing subscriber baseHigh open rates

All sponsored content is clearly labeled per our editorial policy.