Cache-Control Headers Guide: Policies for Static Assets, HTML, APIs, and CDNs

Overview

A cache policy is a delivery decision, not just a performance setting. A long browser or CDN lifetime can reduce origin requests and improve response times, but it can also keep outdated or private content in circulation. A short lifetime improves freshness but may increase requests to the origin and reduce the benefit of edge delivery.

Start by classifying the response before choosing a header. Ask three questions:

• Is the response identical for every visitor, or does it contain private or user-specific data?
• How quickly must a change become visible?
• Can the response be safely refreshed through revalidation or a cache purge?

The most common directives have different jobs. max-age controls how long a browser may use a response without checking the origin. s-maxage provides a shared-cache lifetime for CDNs and reverse proxies when supported. public indicates that a response may be stored by shared caches, while private limits storage to a private cache such as a browser. no-store tells caches not to store the response, and no-cache means a stored response must be revalidated before reuse; it does not mean the response cannot be stored.

For a broader explanation of browser, CDN, and origin behavior, see Cache-Control Headers Explained. If your main goal is faster origin response time, pair header work with the guidance in How to Reduce TTFB With Edge Caching and Origin Optimization.

Checklist by scenario

Versioned static assets

For files such as fingerprinted CSS, JavaScript, fonts, and images, use a long freshness period when the URL changes whenever the file changes. A filename such as app.abc123.js lets you publish a replacement without relying on every cache to notice that the old content changed.

• Confirm that the build process changes the URL when file contents change.
• Use a shared-cache policy when the asset contains no visitor-specific data.
• Consider immutable only when the URL is genuinely immutable and your deployment process can replace it with a new URL.
• Set an appropriate content type and compression policy separately from caching.
• Test that the CDN and browser receive the intended lifetime.

If assets are not versioned, use a shorter lifetime or plan a reliable purge process. A purge can be useful, but it should not replace cache-busting where frequent updates are expected.

HTML pages and publishing workflows

Public HTML can often benefit from edge caching, but the correct policy depends on how often pages change and whether the CDN can purge or revalidate them. For editorial pages, product listings, and landing pages, define a maximum acceptable period for serving older content and document the release process.

• Separate public pages from account, checkout, cart, and administrative routes.
• Use public only when the response is safe for shared delivery.
• Use s-maxage when the edge should have a different lifetime from the browser.
• Configure purge or revalidation for urgent corrections and major publishing events.
• Check query-string handling so tracking parameters do not create unnecessary cache variants.

WordPress sites should review page-cache exclusions for logged-in users, preview URLs, comment submissions, and ecommerce sessions. The article on Cloudflare APO vs. Traditional WordPress Caching Plugins provides useful context when comparing edge delivery with plugin-based caching.

Images, downloads, and media

Public images and other large files are usually good candidates for CDN delivery when they do not expose private information. Use stable, versioned URLs where possible. For user-uploaded files, confirm whether access should be public, restricted, or protected through signed requests before enabling shared caching.

• Check whether the URL reveals private or temporary content.
• Choose a policy that matches the replacement workflow.
• Verify range-request and download behavior for large files.
• Use purge or a new URL when an asset must be withdrawn quickly.

APIs and dynamic responses

API caching requires a more careful cache key and authorization review. A response may be cacheable only for a short period, only for anonymous requests, or not at all. A useful starting point is How to Cache APIs Safely.

• Do not share a response between users unless the cache key and response policy guarantee that it is safe.
• Review the effect of Authorization, cookies, language, device, and other request inputs.
• Use Vary only for request headers that genuinely change the representation; unnecessary variation reduces the cache hit ratio.
• Define whether stale data is acceptable for the endpoint.
• Test error responses as well as successful responses, because an incorrectly cached error can affect many users.

For a public, read-only endpoint, a short shared-cache lifetime with revalidation may be appropriate. For account data, payment information, or other sensitive responses, prefer a private or no-store policy unless the complete architecture has been reviewed.

What to double-check

Inspect the complete response path rather than relying on the origin configuration alone. A CDN, reverse proxy, web server, application framework, and browser may each apply caching behavior. Use browser developer tools and response-header inspection to compare what the origin sends with what the edge returns.

• Cache status: Identify whether the response was a hit, miss, bypass, or revalidation. Header names vary by provider, so treat them as diagnostic signals rather than universal standards.
• Effective lifetime: Confirm both browser freshness and shared-cache freshness. A CDN may honor s-maxage differently from max-age.
• Cache key: Review host, path, query parameters, cookies, authorization, and selected request headers.
• Variation: Check Vary, content negotiation, language selection, and compression variants.
• Purging: Test a targeted purge and document how to perform a broader purge during an incident.
• Revalidation: Confirm that entity tags or modification dates work as expected when the response uses validators.
• Cookies: Make sure session or personalization cookies do not unintentionally make public pages private or create unsafe cache behavior.

Keep a small test matrix for anonymous and authenticated requests, desktop and mobile variants, common query strings, and recently published content. A CDN comparison should include these operational controls, not only geographic coverage or price.

Common mistakes

Using no-cache when you mean no-store. These directives are not interchangeable. The former permits storage but requires validation before reuse; the latter is intended to prevent storage.

Caching personalized HTML. A page that includes a user name, account balance, cart, or permissions should not be shared merely because the URL looks public. Separate public and private routes, or bypass the shared cache when personalization is present.

Applying one policy to every content type. Static assets, HTML, APIs, and sensitive responses have different freshness and risk profiles. Build rules by route or response class.

Ignoring deployment behavior. Long-lived assets without versioned URLs create stale-content problems. Conversely, purging every asset on every release can reduce the value of caching and increase load on the origin.

Forgetting error responses. Confirm how the CDN handles redirects, authentication failures, server errors, and maintenance pages. Set explicit rules where the default behavior is unsuitable.

Changing headers without measuring the result. Track cache hit ratio, origin requests, response age, purge outcomes, and user-visible freshness. A policy is successful only when it balances performance, correctness, and operational control.

When to revisit

Review cache-control headers before seasonal traffic periods, major product launches, content migrations, or changes to your CDN, reverse proxy, hosting platform, or deployment workflow. Revisit them whenever the application adds personalization, a new API, login flows, ecommerce features, or a different asset pipeline.

Use this short operating checklist:

1. List public, private, static, dynamic, and sensitive routes.
2. Assign a freshness target and acceptable stale window to each group.
3. Write the intended browser and shared-cache directives.
4. Test cache keys, cookies, authorization, query strings, and variants.
5. Verify hits, misses, revalidation, and purges from more than one client state.
6. Record the owner and procedure for emergency invalidation.

Update the checklist when your workflows or tools change, and repeat it before each major seasonal planning cycle. If you are selecting infrastructure as part of the review, compare operational requirements in Best CDN for Small Websites and distinguish a CDN from an origin-side reverse proxy cache. Clear policies, tested cache rules, and a documented purge path make edge caching easier to operate safely over time.