CDN cache keys and query strings: why the right cache header may still do nothing
A cache can miss on every request or never store a response at all, even with a sensible Cache-Control header. Start with the cache key, verify real responses and plan invalidation.
Vishwaka Bandara
A public endpoint can have a technically correct cache header and still provide no protection against repeat traffic. Two questions decide whether caching helps: what request variations map to the same cache key, and does the deployed path actually cache the response?
Answer both with live requests before calling an optimisation finished. A header expresses cache policy. It does not prove that every CDN, gateway or framework layer in front of the endpoint will store and reuse the response.
Key takeaways
- Write down the cache key. Irrelevant query parameters can turn one public response into unlimited cache misses.
- Do not cache private or personalised output. Public caching belongs only on content that is safe for every recipient.
- Verify caching at the real deployed address. Inspect response headers and repeated requests, not only configuration.
- Plan invalidation before choosing a long TTL. A short safety window plus explicit clearing is often safer for business-critical public data.
A cache key decides what counts as the same request
A cache stores a response under a key. A CDN can include the URL path, query string, headers, cookies and other dimensions in that key. Cloudflare’s cache-key documentation describes those components and the options for customising them.
Suppose a public price endpoint ignores query parameters. To the application, `/prices?x=1` and `/prices?x=2` are identical. If the CDN treats them as separate keys, both requests miss the stored response and reach the origin. A script that changes an irrelevant parameter can turn a cache into a pass-through.
Choose a policy for irrelevant query strings
Pick the narrowest approach that matches the endpoint contract. Never ignore a parameter that changes price, locale, experiment, authorisation or any response content. Cache correctness is a privacy and data-integrity decision, not just a performance detail.
Understand what Cache-Control asks caches to do
A header such as `Cache-Control: public, max-age=60, s-maxage=300` gives different instructions to a browser and a shared cache. MDN’s Cache-Control reference explains directives including `public`, `no-store`, `max-age` and `s-maxage`. A private or error response may need stricter directives than a successful public response.
Set these directives intentionally, but do not mistake them for an observation. A platform may bypass caching for dynamic routes, cookies, headers or its own product rules. Test a sequence of real requests and inspect the cache-status and Age headers supplied by the infrastructure you actually use.
Verify the deployed behaviour
- Request the canonical URL repeatedly. Confirm whether a response is stored and whether the origin is avoided.
- Request harmless query-string variants. Confirm they share the intended behaviour or are redirected or rejected.
- Test success, error and authenticated cases separately. Caching a failure or private response can be worse than no caching.
- Run the test against production-like routing. Proxies and function gateways can rewrite a path differently from local development.
- Record the result in monitoring. A later configuration change can silently turn a hit into a miss.
Pair a safety TTL with explicit invalidation
Public data such as catalogue information or published prices needs a freshness plan. An explicit invalidation lets the product clear the affected value when an operator changes it. A modest time-to-live then limits the impact if that invalidation is missed.
In Next.js, a cache tag can group related data so a route handler or server function can revalidate the tag on a deliberate change. The exact mechanism varies by platform, but the design principle remains: name the cached thing, clear it at the source of change and retain a bounded fallback lifetime.
Apply the same discipline in the browser
Client-side data caches also use keys. A key that is too specific creates duplicated copies of identical public data. A key that is too broad can display one tenant’s data while another tenant is active. Include the values that genuinely change the answer, keep their positions consistent and clear the relevant keys when that context changes.
The cache key is part of the data model. Treat it with the same care you give an API parameter or database constraint.
A cache review checklist
- Classify the response. Confirm it is public and non-personalised before allowing shared caching.
- Specify the cache key. State which path, query, header and cookie dimensions matter.
- Canonicalise or reject noise. Do not let irrelevant URL variants create unlimited misses.
- Verify live headers and repeated requests. Configuration is not evidence of a cache hit.
- Define invalidation and a safety TTL. Freshness should have both an active and passive path.
A cache is real only when the response proves it
Caching is valuable because it changes the real work a system performs under repeat demand. That benefit is earned by a correct key, a response safe to share and evidence from the deployed route. Start there, and a performance header becomes an operational control rather than decoration.
Ready when you are