Skip to main content

3. Storing Responses in Caches

A cache MUST NOT store a response to a request unless all of the following conditions are met:

  • The request method is understood by the cache;

  • The response status code is final (Final) (see Section 15 of [HTTP]);

  • If the response status code is 206 or 304, or a must-understand cache directive is present (see Section 5.2.2.3): the cache understands the response status code;

  • The no-store cache directive is not present in the response (see Section 5.2.2.5);

  • If the cache is shared: the private response directive is not present or allows shared caches to store a modified response; see Section 5.2.2.7);

  • If the cache is shared: the Authorization header field (see Section 11.6.2 of [HTTP]) is not present in the request or a response directive explicitly allows shared caches; see Section 3.5); and

  • The response contains at least one of the following:

    • A public response directive (see Section 5.2.2.9);

    • A private response directive, if the cache is not shared (see Section 5.2.2.7);

    • An Expires header field (see Section 5.3);

    • A max-age response directive (see Section 5.2.2.1);

    • If the cache is shared: an s-maxage response directive (see Section 5.2.2.10);

    • A cache extension that allows caching (see Section 5.2.3); or

    • A status code defined as heuristically cacheable (Heuristically Cacheable) (see Section 4.2.2).

Note that cache extensions can override any of the requirements listed above; see Section 5.2.3.

In this context, a cache "understands (Understood)" a request method or response status code if the cache recognizes it and implements all specified cache-related behavior.

Note that, in normal operation, some caches will not store responses that have neither a cache validator (Cache Validator) nor an explicit expiration time, as such responses are often not worth storing. However, caches are not prohibited from storing such responses.

3.1 Storing Header and Trailer Fields​

A cache MUST include all received response header fields when storing a response -- including unrecognized fields; this ensures that new HTTP header fields can be successfully deployed. However, the following exceptions exist:

  • The Connection header field and fields whose names are listed in it MUST be removed before forwarding messages per Section 7.6.1 of [HTTP]. This MAY be achieved by removing them before storing.

  • Likewise, the semantics of some fields require removing them before forwarding messages, which MAY be achieved by removing them before storing; see Section 7.6.1 of [HTTP] for some examples.

  • The no-cache (Section 5.2.2.4) and private (Section 5.2.2.7) cache directives can have parameters that prevent all caches and shared caches, respectively, from storing header fields.

  • Proxy-specific header fields that are used by a cache when forwarding requests MUST NOT be stored unless the cache incorporates the proxy's identity into the cache key. In practice, this is limited to Proxy-Authenticate (Section 11.7.1 of [HTTP]), Proxy-Authentication-Info (Section 11.7.3 of [HTTP]), and Proxy-Authorization (Section 11.7.2 of [HTTP]).

A cache MAY store trailer fields (Trailer Fields) separately from header fields or discard them. Caches MUST NOT combine trailer fields with header fields.

3.2 Updating Stored Header Fields​

In various cases, a cache needs to update the header fields of a stored response from another (typically newer) response; for example, see Sections 3.4, 4.3.4, and 4.3.5.

When doing so, a cache MUST add each header field from the providing response to the stored response, replacing any existing field values, with the following exceptions:

  • Header fields excluded from storage per Section 3.1,

  • Header fields upon which the cache's stored response depends, as described below,

  • Header fields that are automatically processed and removed by the recipient, as described below, and

  • The Content-Length header field.

In some cases, caches (especially in user agents) store the result of processing received responses rather than the responses themselves, and updating header fields that influence that processing could result in inconsistent behavior and security issues. In such cases, caches MAY omit these header fields from updating stored responses in exceptions, but SHOULD limit such omissions to fields necessary to ensure the integrity of the stored response.

For example, a browser might decode a response's content encoding (Content Coding) when it is received, creating a disconnect between its stored data and the response's original metadata. Updating that stored metadata with a different Content-Encoding header field would be problematic. Likewise, a browser might store a parsed HTML tree rather than the content received in the response; updating the Content-Type header field in this situation would not be feasible, as any assumptions made about the format during parsing are now baked in.

Also, some fields are automatically processed and removed by HTTP implementations, such as the Content-Range header field. Even if no processing actually occurs, implementations MAY automatically omit these header fields from updates.

Note that the Content-* prefix does not signify that a header field is omitted from updates; it is a convention for MIME header fields, not HTTP.

3.3 Storing Incomplete Responses​

A cache MAY store an incomplete response (see Section 6.1 of [HTTP]) if the request method is GET, the response status code is 200 (OK), and the entire response header section has been received, provided that the stored response is recorded as incomplete. Likewise, a 206 (Partial Content) response MAY be stored as an incomplete 200 (OK) response. However, a cache MUST NOT store incomplete or partial content responses if the cache does not support the Range and Content-Range header fields or does not understand the range units (Range Units) used in those fields.

A cache MAY complete a stored incomplete response by making subsequent range requests (see Section 14.2 of [HTTP]) and combining successful responses with the stored response as defined in Section 3.4. A cache MUST NOT use an incomplete response to answer a request unless the response has been completed or the request is partial and specifies a range that is entirely within the incomplete response. A cache MUST NOT send a partial response to a client unless it is explicitly marked using the 206 (Partial Content) status code.

3.4 Combining Partial Content​

A response might transfer only a partial representation if the connection closes prematurely or if the request uses one or more Range specifiers (see Section 14.2 of [HTTP]). After several such transfers, a cache might have received several ranges of the same representation. A cache MAY combine these ranges into a single stored response if they all share the same strong validator (Strong Validator) and the cache complies with the client requirements in Section 15.3.7.3 of [HTTP], and reuse that response to satisfy subsequent requests.

When combining a new response with one or more stored responses, a cache MUST update the stored response's header fields using the header fields provided in the new response, as per Section 3.2.

3.5 Storing Responses to Authenticated Requests​

A shared cache MUST NOT use a cached response to a request with an Authorization header field (see Section 11.6.2 of [HTTP]) to satisfy any subsequent request unless the response contains a Cache-Control field with a response directive (Section 5.2.2) that allows it to be stored by a shared cache and the cache conforms to the requirements of that directive for that response.

In this specification, the following response directives have this effect: must-revalidate (Section 5.2.2.2), public (Section 5.2.2.9), and s-maxage (Section 5.2.2.10).

Last updated on