HTTP Cache-Control Guide

Browser cache, CDN cache, API responses, stale content and safe cache header decisions. Last updated August 31, 2026.

MDN defines Cache-Control as an HTTP header whose directives control caching in browsers and shared caches such as proxies and CDNs. The reference lives at MDN Cache-Control. This Formalint guide is a practical field checklist for developers debugging stale assets and API responses.

Start with the actual headers

curl -I https://example.com/app.js
curl -I https://example.com/api/profile
curl -I -H "Cache-Control: no-cache" https://example.com/app.js
curl -I -H "Pragma: no-cache" https://example.com/app.js

Common directives

Directive	Typical use	Review note
`max-age=31536000`	Versioned static assets	Only safe when filenames change on deploy.
`immutable`	Hashed JS, CSS and images	Good for long-lived assets with content hashes.
`no-cache`	Revalidate before reuse	Does not mean "never store"; it means check before using.
`no-store`	Sensitive responses	Use for private account, token or payment data.
`s-maxage`	Shared caches and CDNs	Can differ from browser cache policy.
`private`	User-specific browser cache	Shared caches should not store the response.

Recommended starting policies

# Hashed static asset
Cache-Control: public, max-age=31536000, immutable

# HTML shell
Cache-Control: no-cache

# Public API reference data
Cache-Control: public, max-age=300, stale-while-revalidate=60

# Private account API
Cache-Control: no-store

Debug stale content

Confirm whether the stale response is HTML, JS, CSS, image, API JSON or CDN edge content.
Compare browser DevTools response headers with curl -I.
Check whether a service worker, CDN rule, reverse proxy or application middleware changed headers.
Verify deploy filenames. Long cache is safe for hashed assets, risky for stable names such as app.js.
Record before/after headers in the incident note.

Nginx example

location /assets/ {
    add_header Cache-Control "public, max-age=31536000, immutable";
}

location / {
    add_header Cache-Control "no-cache";
}

Cache review checklist

url:
resource type:
cache-control:
etag:
last-modified:
cdn cache status:
service worker involved:
safe to cache:
user-specific data present:
fix:

Strong caching is excellent for performance, but only when the resource can safely be reused. Cache public versioned assets aggressively; treat user-specific API responses with much more suspicion.