A CDN cache key determines which requests share a cached response and which must be stored separately. This guide explains what to include, what to exclude, how to investigate cache misses and stale content, and which checks to repeat after deployments or configuration changes.
Overview
A cache key is the identifier a CDN uses to find a stored response for an incoming request. In a simple setup, the key may be based mainly on the URL. In a more complex setup, it can also vary by query string, selected cookies, request headers, device type, language, or another property that changes the response.
The design goal is not to include everything available in the request. It is to include every input that can legitimately change the response, while excluding values that do not. Including too little can serve the wrong content. Including too much can create many small cache variants, increase CDN cache misses, and reduce the value of edge caching.
For example, a tracking parameter such as utm_source often does not change the page itself. If it is included in the cache key, every campaign URL may create a separate cache entry. By contrast, a parameter such as page=2 changes the requested content and normally belongs in the key. The correct treatment depends on the application, so cache-key decisions should be based on observed response behavior rather than parameter names alone.
Keep cache keys separate from cache permissions. A well-designed key does not make private or authenticated content safe to cache publicly. Authentication, authorization, and response privacy must be handled through explicit CDN rules, origin behavior, and appropriate Cache-Control directives.
What to track
Document each variable that can affect a cacheable response. The following reference table is a practical starting point for a CDN cache key review.
| Request input | Typical treatment | What to verify |
|---|---|---|
| Path and hostname | Include | Confirm that the host and path identify the intended site, locale, or application. |
| Query strings | Include only response-changing parameters | Separate pagination, filtering, or search inputs from analytics and campaign parameters. |
| Cookies | Usually exclude for public pages; bypass or vary carefully | Check whether a cookie changes currency, login state, experiments, cart data, or personalization. |
| Authorization | Do not make private responses publicly shareable | Use a bypass or private-cache policy unless the application has a deliberate, secure design. |
| Request headers | Vary only on selected headers | Identify headers that change the representation, such as language or content negotiation. |
| Device or client class | Use only when the response differs | Prefer responsive markup where possible; otherwise confirm that each device variant is necessary. |
| Compression format | Usually handled by the CDN | Ensure compressed and uncompressed responses are not mixed and that the CDN honors content negotiation correctly. |
| Localization | Include locale when content differs | Check whether language is expressed in the path, hostname, cookie, or request header, and use one consistent source. |
| HTTP method | Cache safe, explicitly supported methods only | Do not treat state-changing requests as ordinary page-cache requests. |
Query strings
Query-string handling is one of the most common sources of unexpected cache behavior. Create an allowlist of parameters that change the representation, such as sorting, filtering, pagination, or a product identifier. Remove or ignore known tracking parameters only when doing so cannot alter the response or application behavior. If the CDN supports query-string normalization, use it consistently and test the normalized URL at the origin and edge.
Cookies and personalization
A cookie should affect the cache key only when it changes the response and when creating a separate public variant is safe and useful. Login cookies, shopping-cart cookies, and account-specific values generally require a bypass or private response. For a public page with a small number of deliberate variants, such as currency or language, a narrowly defined variation may be appropriate. Avoid varying on the complete Cookie header: it can create an effectively unique cache entry for many visitors.
Headers, devices, and formats
Headers such as Accept-Language or Accept can produce different representations, but varying on a broad header without normalization can fragment the cache. Device-specific caching deserves the same scrutiny. If desktop and mobile responses are genuinely different, track the classification method and test both variants. Compression formats should normally be managed by the CDN's content-negotiation layer rather than manually added as arbitrary key components.
Cache status and response metadata
Track the CDN's cache-status headers, age information, selected Cache-Control directives, and any diagnostic headers exposed by your provider. Record the URL tested, request headers, cookies, query string, edge location if available, response status, and whether the result was a hit, miss, bypass, or revalidation. A cache hit alone is not proof that the correct representation was served.
Cadence and checkpoints
Review cache-key behavior on a monthly or quarterly schedule, and perform an additional review whenever a change could affect the response. A lightweight recurring process is more useful than an occasional investigation after a customer reports wrong content.
- Record a baseline. Select representative public pages, filtered URLs, localized pages, static assets, and any cacheable API responses. Save their expected content and relevant response headers.
- Test a clean request. Request each URL more than once from a controlled client. Compare the first response with subsequent responses and note cache status, age, and time to first byte.
- Test meaningful variants. Change one input at a time: a valid filter, an ignored tracking parameter, a language value, a device classification, or a relevant cookie. Confirm that only intended variants share a cache entry.
- Test sensitive paths. Check login, account, checkout, cart, preview, administration, and other private routes. Confirm that they bypass public CDN caching or return an explicitly private response.
- Test invalidation. Publish or update a controlled page, purge the relevant object, and confirm that the updated response becomes available. Also test the behavior before and after the normal TTL expires.
- Compare edge and origin logs. A CDN hit may not reach the origin, while a bypass or miss should normally produce an origin request. Differences help identify whether the problem is in the key, TTL, purge process, or origin headers.
Repeat this checklist after a CDN migration, domain or DNS change, cache-rule edit, framework upgrade, personalization release, localization rollout, or change to authentication. Keep the test URLs and expected outcomes in version control so that configuration reviews remain reproducible.
How to interpret changes
A rising cache-miss rate does not automatically mean the cache key is wrong. It may reflect a new deployment, a shorter TTL, a purge, a new traffic pattern, an origin error, or an increase in unique query strings. Start by segmenting results by hostname, path, status code, cache rule, and response type.
If two requests with different tracking parameters produce misses but identical content, check whether those parameters can be excluded from the key. If two requests with different languages produce the same cached language, the key may omit a response-changing input. If authenticated and anonymous requests appear to share an object, treat it as a security incident and bypass the affected route while investigating.
Unexpectedly stale content usually points to TTL, revalidation, purge propagation, or an intermediate cache rather than the key alone. Check the response's Age, Cache-Control, ETag, and Last-Modified behavior, then compare the edge response with the origin response. A cache miss that remains slow may indicate an origin or DNS performance issue; a cache hit that remains slow may indicate a large response, a slow edge path, or client-side work after delivery.
When the cache has too many variants, inspect the highest-cardinality inputs first: full cookies, arbitrary query strings, unnormalized language values, and overly broad device or header variation. Reduce variation only after confirming that the removed input cannot change the response. Cache efficiency is useful, but correctness and privacy take priority.
When to revisit
Schedule a cache-key review at least monthly or quarterly, depending on how often the site changes. Revisit immediately after any release that adds personalization, search or filtering, A/B testing, localization, new authentication flows, ecommerce cart behavior, or cacheable API endpoints. Also review the configuration when changing CDN providers, cache rules, origin headers, domain routing, or DNS infrastructure.
End each review with a short record: what changed, which URLs were tested, which inputs belong in the key, which paths bypass caching, and whether purge and revalidation behaved as expected. Update the test set when the site gains a new content type or response variant. This turns cache debugging from guesswork into a repeatable part of website performance and reliability work.
For related implementation work, use the CDN and Edge Caching Setup Guide when defining cache rules and TTLs, and consult the Cache-Control Headers and TTL Settings guide when aligning origin headers with edge behavior. If the response is an API, review How to Cache APIs Safely before enabling public caching.