The HTTP Cache-Control header is used for both HTTP requests and HTTP responses. It is responsible for holding directives related to controlling caches for clients and intermediaries.
The Cache-Control header is used to control caches in client browsers and intermediate services such as proxies and content delivery networks (CDNs). Several directives are used for HTTP requests, HTTP responses, or both.
Clients may not support all of the directives. When an client encounters a directive that it does not recognize or support, then the directive will be ignored.
max-age directive is used by a client to indicate that responses stored within the specified number of seconds will be accepted. Invalid values for
max-age, such as a negative value or a string literal, are generally be treated as
max-age=0 is sometimes used to indicate that the cache is not to be used. This is an artifact of HTTP/1.0, as many implementations did not support the no-cache directive.
The max-stale directive is used by a client to indicate that they will accept stale HTTP responses up to a certain number of seconds. This differs from
max-stale begins once the
This directive might be used by a client when an origin server is offline, and HTTP responses that are a little bit old are generally still acceptable.
min-fresh directive is used by a client to indicate that it will allow a stored HTTP response that will remain fresh for a specified number of seconds. Essentially, this requires that the HTTP response not only be fresh but also that it won’t be updated for a minimum amount of time.
A client sends the
no-cache directive to require the cache to validate the HTTP response in advance of sending it. This is sometimes used to force the reloading of a resource.
To prevent a cache from storing a response, the
no-store directive is used.
A client sends the
no-store directive to ask caches not to store the HTTP request or the corresponding HTTP response.
A client sends the
no-transform directive if the HTTP response is not to be manipulated. For example, graphics files might normally be scaled by a content provider to save bandwidth but this directive prevents such actions. Regardless of whether an intermediary is responsible for Caching or simply forwarding, this directive holds.
A client sends the
only-if-cached directive to HTTP request that any stored HTTP response is expected to be returned.
max-age directive is sent by a server to indicate that the HTTP response will remain fresh for a specified number of seconds after it is generated. Essentially, it informs caches how long it will remain fresh. Importantly, the number of seconds indicates the period from which the content was generated, as opposed to received. This means that any time spent in transit or stored in the caches of intermediaries is deducted from the allowance.
s-maxage, shared max-age, directive is the same as
max-age, except that it is intended for shared caches such as proxy servers. When both
max-age are included, a shared cache will ignore the latter.
no-cache directive is sent by the server to direct caches to first validate responses from the origin server before sending them.
If the intention is to direct caches not to store the result then the
no-store directive is recommended to be used instead.
A server includes the
no-store directive to prevent the storing of the HTTP response in any cache.
A server sends the
no-transform directive to ensure that intermediaries do not manipulate the HTTP response before it is forwarded to the client, regardless of whether it is cached.
The server sends the
must-understand directive to indicate that caches is expected to store the HTTP response only in cases where it recognizes the status code and understands the requirements.
For fallback purposes, the
must-understand directive is recommended to be used in conjunction with
no-store in the case the
must-understand directive is unsupported by a cache and thus ignored.
Cache-Control: must-understand, no-store
private directive is sent by a server to instruct that the HTTP response can only be stored in a private cache, such as the one maintained by an end user's browser.
public directive is included in a server’s HTTP response to indicate that it can be stored in a shared cache. Caches are not permitted to store HTTP responses that contain the HTTP Authorization header unless they are accompanied by the
public directive is unnecessary if
s-maxage are present in the HTTP response.
immutable directive indicates a guarantee by the server that the HTTP response will not be updated while it is still fresh. This can be used to avoid unnecessary conditional HTTP requests.
When a server sends the
stale-while-revalidate directive, it extends the period that it can be reused for. Specifically, after a HTTP response is stale, it can be reused provided that the HTTP response is validated in the background.
Once revalidated, the cache will once again appear fresh. This process is used to obscure the latency involved in revalidating the response.
The server includes the
must-revalidate directive to instruct caches that they can reuse the HTTP response as long as it is fresh. After the HTTP response expires, it must be validated before serving it. This is intended to prevent the reuse of stale HTTP responses when they are disconnected from the origin server.
If the cache is not able to validate the HTTP response then a 504 Gateway Timeout response will be returned.
proxy-revalidate directive is identical to
must-revalidate, except that it is intended for shared caches such as proxy servers and CDNs.
stale-if-error directive is included in a HTTP response, it means that a stale HTTP response can be used when the origin server is reporting one of the following HTTP error response status codes:
After the HTTP response is stale, as long as it is within the specified number of seconds that the server is responding with one of these 5XX error codes, the HTTP response can be reused.
Multiple directives can be sent with multiple Cache-Control HTTP headers or the same line in a comma-delimited format. In either case, if conflicting directives are specified then the most restrictive combination will be applied.
The Cache-Control header is used to hold various cache-related instructions that can apply to HTTP requests, HTTP responses, or both. A variety of use cases can be covered using appropriate combinations of directives.