Cache-Control

The HTTP Cache-Control header carries directives controlling how browsersproxiesand CDNs store and serve cached responses. Both requests and responses use this header to coordinate Caching behavior across the entire delivery chain.

Usage

Originsintermediariesand clients all rely on Cache-Control to agree on when a stored response remains usable and when a fresh copy is needed. A single response often combines several directives to express a complete caching policy: how long to store, who is allowed to storeand what to do once freshness expires.

The table below shows which directives apply to requestsresponsesor both.

Directive	Request	Response
max-age	X	X
max-stale	X
min-fresh	X
s-maxage		X
no-cache	X	X
no-store	X	X
no-transform	X	X
only-if-cached	X
must-revalidate		X
proxy-revalidate		X
must-understand		X
private		X
public		X
immutable		X
stale-while-revalidate		X
stale-if-error	X	X

Multiple directives are separated by commas in a single header value or split across multiple Cache-Control headers. When conflicting directives appearthe most restrictive combination applies.

Request directives

max-age

The max-age directive tells caches to return a stored response only if the response is no older than the specified number of seconds. Invalid values such as negative numbers are treated as 0.

Cache-Control: max-age=<seconds>

Setting max-age=0 forces end-to-end revalidation. This pattern originated in HTTP/1.0 implementations lacking no-cache support.

max-stale

The max-stale directive signals acceptance of a response whose Age has exceeded the freshness lifetime by up to the given number of seconds. The tolerance window starts once max-age expires.

Cache-Control: max-stale=<seconds>

This directive is useful when an origin server is temporarily unreachable and a slightly stale response is acceptable.

min-fresh

The min-fresh directive requests a stored response whose remaining freshness lifetime is at least the specified number of seconds. The cache returns the stored copy only if the response will stay fresh for the additional period.

Cache-Control: min-fresh=<seconds>

no-cache

A request carrying no-cache requires the cache to validate the stored response with the origin before serving the copy. This forces revalidation without discarding the stored entry.

Cache-Control: no-cache

no-store

The no-store directive asks caches not to store the request or the corresponding response.

Cache-Control: no-store

no-transform

The no-transform directive forbids intermediaries from modifying the response bodysuch as recompressing images or converting media formats. The restriction applies whether the intermediary is a Caching proxy or a forwarding gateway.

Cache-Control: no-transform

only-if-cached

The only-if-cached directive tells the cache to return a stored response without contacting the origin. If no suitable stored response existsthe cache returns a 504 status.

Cache-Control: only-if-cached

Response directives

max-age

The max-age directive declares the number of seconds the response remains fresh after generation. The timer starts from the moment the origin creates the response, so transit time and time spent in intermediate caches count against the budget.

Cache-Control: max-age=<seconds>

A response with max-age=3600 stays fresh for one hour. After the hour elapsescaches treat the response as stale and either revalidate or fetch a new copy depending on other directives present.

s-maxage

The s-maxage (shared max-age) directive overrides max-age for shared caches such as CDNs and proxy servers. Private browser caches ignore s-maxage and fall back to max-age.

Cache-Control: s-maxage=<seconds>

no-cache

The response no-cache directive requires caches to revalidate the stored response with the origin before every reuse. The cache still stores the responseenabling conditional requests with ETag or Last-Modified.

Cache-Control: no-cache

no-store

The no-store directive prevents any cache from storing the response. Every subsequent request goes to the origin.

Cache-Control: no-store

no-transform

The response no-transform directive prevents intermediaries from altering the response body before forwardingwhether the intermediary caches the content or not.

Cache-Control: no-transform

must-revalidate

The must-revalidate directive allows caches to serve the response while fresh. Once stalethe cache contacts the origin to revalidate before serving the response again. If the origin is unreachablethe cache returns a 504 instead of serving stale content.

Cache-Control: must-revalidate

proxy-revalidate

The proxy-revalidate directive works identically to must-revalidateexcept the requirement applies only to shared caches. Private browser caches are not affected.

Cache-Control: proxy-revalidate

must-understand

The must-understand directive instructs a cache to store the response only when the cache recognizes the status code and understands the associated caching requirements.

Cache-Control: must-understandno-store

Pairing must-understand with no-store provides a fallback: caches lacking support for must-understand ignore the unknown directive and honor no-store instead.

private

The private directive restricts storage to private cachestypically the end user's browser. Shared caches such as CDNs and proxy servers discard the response.

Cache-Control: private

public

The public directive marks a response as eligible for storage in shared caches. Responses carrying an Authorization header are not stored by shared caches unless the public directive is present.

Cache-Control: public

immutable

The immutable directive guarantees the response body will not change during the freshness lifetime. Caches skip conditional requests for immutable resourceseliminating revalidation round trips for assets like versioned JavaScript bundles or fingerprinted images.

Cache-Control: publicmax-age=31536000immutable

stale-while-revalidate

The stale-while-revalidate directive extends the usability window of a stale response. After freshness expirescaches serve the stale copy while revalidating in the background. The parameter defines how many additional seconds the stale response remains acceptable.

Cache-Control: max-age=600stale-while-revalidate=30

Once the background revalidation completesthe cache replaces the stale entry with the fresh response. This pattern hides revalidation latency from end users.

stale-if-error

The stale-if-error directive allows caches to serve a stale response when the origin returns an error status (500502503or 504) or is unreachable. The parameter sets the number of seconds beyond the freshness lifetime during which the stale response remains usable as a fallback.

Cache-Control: max-age=600stale-if-error=86400

Example

A static asset served with a long freshness lifetime and the immutable flag. The browser and any shared cache store this response for one year without revalidation.

Cache-Control: publicmax-age=31536000immutable

An API response intended only for the requesting browser. The cache stores the response for five minutes and revalidates before reuse once stale.

Cache-Control: privatemax-age=300must-revalidate

A CDN-targeted policy giving the shared cache a ten-minute window while the browser cache gets one minute. Stale responses are served for up to 30 seconds while the CDN revalidates in the background.

Cache-Control: s-maxage=600max-age=60stale-while-revalidate=30

Takeaway

The Cache-Control header coordinates caching across browsersproxiesand CDNs through a set of composable directives. Combining freshness lifetimes, revalidation rulesand staleness tolerances gives origin servers precise control over how responses are stored and served throughout the delivery chain.

See also

• RFC 9111: HTTP Caching
• RFC 5861: Cache-Control Extensions for Stale Content
• Google: HTTP caching for crawlers
• Google Search Blog: Crawling DecemberHTTP caching
• Caching
• Conditional requests
• ETag
• Last-Modified
• Expires
• Age
• Vary
• HTTP headers