Skip to main content

3. Storing Responses in Caches

A cache MUST NOT store a response to any request, unless:

  • The request method is understood by the cache and defined as being cacheable, and

  • the response status code is understood by the cache, and

  • the "no-store" cache directive (see Section 5.2) does not appear in request or response header fields, and

  • the "private" response directive (see Section 5.2.2.6) does not appear in the response, if the cache is shared, and

  • the Authorization header field (see Section 4.2 of [RFC7235]) does not appear in the request, if the cache is shared, unless the response explicitly allows it (see Section 3.2), and

  • the response either:

    • contains an Expires header field (see Section 5.3), or

    • contains a max-age response directive (see Section 5.2.2.8), or

    • contains a s-maxage response directive (see Section 5.2.2.9) and the cache is shared, or

    • contains a Cache Control Extension (see Section 5.2.3) that allows it to be cached, or

    • has a status code that is defined as cacheable by default (see Section 4.2.2), or

    • contains a public response directive (see Section 5.2.2.5).

Note that any of the requirements listed above can be overridden by a cache-control extension; see Section 5.2.3.

In this context, a cache has "understood" a request method or a response status code if it recognizes it and implements all specified caching-related behavior.

Note that, in normal operation, some caches will not store a response that has neither a cache validator nor an explicit expiration time, as such responses are not usually useful to store. However, caches are not prohibited from storing such responses.

3.1. Storing Incomplete Responses​

A response message is considered complete when all of the octets indicated by the message framing ([RFC7230]) are received prior to the connection being closed. If the request method is GET, the response status code is 200 (OK), and the entire response header section has been received, a cache MAY store an incomplete response message body if the cache entry is recorded as incomplete. Likewise, a 206 (Partial Content) response MAY be stored as if it were an incomplete 200 (OK) cache entry. However, a cache MUST NOT store incomplete or partial-content responses if it does not support the Range and Content-Range header fields or if it does not understand the range units used in those fields.

A cache MAY complete a stored incomplete response by making a subsequent range request ([RFC7233]) and combining the successful response with the stored entry, as defined in Section 3.3. A cache MUST NOT use an incomplete response to answer requests unless the response has been made complete or the request is partial and specifies a range that is wholly within the incomplete response. A cache MUST NOT send a partial response to a client without explicitly marking it as such using the 206 (Partial Content) status code.

3.2. Storing Responses to Authenticated Requests​

A shared cache MUST NOT use a cached response to a request with an Authorization header field (Section 4.2 of [RFC7235]) to satisfy any subsequent request unless a cache directive that allows such responses to be stored is present in the response.

In this specification, the following Cache-Control response directives (Section 5.2.2) have such an effect: must-revalidate, public, and s-maxage.

Note that cached responses that contain the "must-revalidate" and/or "s-maxage" response directives are not allowed to be served stale (Section 4.2.4) by shared caches. In particular, a response with either "max-age=0, must-revalidate" or "s-maxage=0" cannot be used to satisfy a subsequent request without revalidating it on the origin server.

3.3. Combining Partial Content​

A response might transfer only a partial representation if the connection closed prematurely or if the request used one or more Range specifiers ([RFC7233]). 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, and reuse that response to satisfy later requests, if they all share the same strong validator and the cache complies with the client requirements in Section 4.3 of [RFC7233].

When combining the new response with one or more stored responses, a cache MUST:

  • delete any Warning header fields in the stored response with warn-code 1xx (see Section 5.5);

  • retain any Warning header fields in the stored response with warn-code 2xx; and,

  • use other header fields provided in the new response, aside from Content-Range, to replace all instances of the corresponding header fields in the stored response.