Vary header and cache keys

Your CDN hit rate is 5% despite setting max-age=3600. The dashboard shows thousands of unique cache entries per URL. Somewhere in the origin response headers there is a Vary line that is silently fragmenting every URL into thousands of separate cache keys — one per unique browser header combination. This is the most common CDN misconfiguration in production.

How the cache key is built

A CDN cache stores responses indexed by a cache key. The default key is (URL, HTTP method, Host). The Vary response header extends the key with additional request header dimensions:

Cache-Control: public, max-age=3600
Vary: Accept-Encoding, Accept-Language

This tells the cache: maintain separate entries for each distinct value of Accept-Encoding and Accept-Language. A request for /page with Accept-Language: en and another with Accept-Language: ru create two separate cache entries — both correct language versions are served from cache.

RFC 7234 §4.1 formalises this: “A cache MUST use the value of the Vary header field to determine if a stored response may be used for a given request.”

The Vary footgun

Vary works correctly for Accept-Encoding (gzip vs brotli — ~5 distinct values) and Accept-Language (~10–50 values per site). But some headers have thousands or millions of distinct values:

Vary: User-Agent is the classic footgun: developers add it to serve different HTML for mobile vs. desktop. The result is one cache entry per unique User-Agent string — every Chrome release, every iOS version, every Safari build. The cache fills up with unique entries that will never be reused; hit rate plummets to near zero.

Cookies are NOT in the cache key by default

This is the most security-relevant Vary fact. Cookies are not part of the default cache key. If an endpoint reads a session cookie and returns personalised content:

• Missing Cache-Control: private → CDN caches the personalised response
• Missing Vary: Cookie → different users with different cookies get the same cached response

Result: one user’s account page is served to another user — a data leak.

Rule of thumb: for any endpoint that reads a cookie, set Cache-Control: private. Only use Vary: Cookie if you need CDN caching for cookie-differentiated content (rare, complex, requires a cookie whose value is stable and low-cardinality).