NGINX proxy_cache_valid: Status Code Retention, Upstream Header Precedence, and proxy_ignore_headers

In NGINX configurations using ngx_http_proxy_module, the proxy_cache_valid directive sets caching durations for different HTTP response status codes when proxy caching is enabled. However, parameters of caching can also be returned directly by the proxied server in upstream response headers. By default, caching parameters returned in upstream response headers take higher priority than caching times configured with proxy_cache_valid. Using the proxy_ignore_headers directive disables the processing of designated backend response headers, which prevents those specific headers from setting caching parameters.

Status-Code Retention with proxy_cache_valid

The proxy_cache_valid directive sets caching time for different response codes within an enabled proxy cache configuration. It does not enable caching on its own; it configures retention times for cached responses. The directive is valid in the http, server, and location contexts:

proxy_cache_valid [code ...] time;

The directive applies durations based on how status codes are specified:

• Explicit response codes: Setting specific codes applies the duration to those responses. For example, proxy_cache_valid 200 302 10m; sets 10 minutes of caching for responses with codes 200 and 302, and proxy_cache_valid 404 1m; sets 1 minute for responses with code 404.
• Omitted response codes: If only a caching time is specified without codes, such as proxy_cache_valid 5m;, only 200, 301, and 302 responses are cached.
• The any parameter: Specifying any caches any response code for the designated time:

  proxy_cache_valid 200 302 10m;
  proxy_cache_valid 301 1h;
  proxy_cache_valid any 1m;

Upstream Response Header Precedence and Rules

Parameters of caching can also be set directly in response headers returned by the proxied server. When present and processed, setting parameters in the response header has higher priority than setting caching time using the proxy_cache_valid directive.

The documented rules and header behaviors include:

• X-Accel-Expires: Sets the caching time of a response in seconds. A value of 0 disables caching for a response. If the value starts with the @ prefix, it sets an absolute time in seconds since Epoch up to which the response may be cached.
• Expires and Cache-Control: If the response header does not include the X-Accel-Expires field, parameters of caching may be set in the header fields Expires or Cache-Control.
• Set-Cookie: If the response header includes the Set-Cookie field, such a response will not be cached by default. In proxy_ignore_headers, ignoring Set-Cookie was introduced in version 0.8.44.
• Vary: If the response header includes the Vary field with the special value *, such a response will not be cached (introduced in version 1.7.7). If the header includes Vary with another value, the response will be cached taking into account the corresponding request header fields (introduced in version 1.7.7).

Disabling Upstream Header Processing with proxy_ignore_headers

Processing of response header fields from the proxied server can be disabled using the proxy_ignore_headers directive. It is valid in the http, server, and location contexts:

proxy_ignore_headers field ...;

The directive accepts fields that control caching as well as redirection, buffering, charset, and rate limiting:

• X-Accel-Expires, Expires, and Cache-Control
• Set-Cookie (appeared in version 0.8.44)
• Vary (appeared in version 1.7.7)
• X-Accel-Redirect (performs an internal redirect to the specified URI)
• X-Accel-Limit-Rate, X-Accel-Buffering, and X-Accel-Charset (each appeared in version 1.1.6)

If not disabled, processing of X-Accel-Expires, Expires, Cache-Control, Set-Cookie, and Vary sets the parameters of response caching. Using proxy_ignore_headers stops NGINX from processing the specified header fields from the proxied server. While disabling these headers prevents them from setting caching parameters or blocking caching under their documented rules, it does not guarantee that local proxy_cache_valid directives alone dictate every caching outcome, as overall caching still depends on whether caching is configured and enabled.

Operational considerations: When enabled, default header processing enforces specific boundaries. For instance, the presence of Set-Cookie or a Vary: * header normally prevents a response from being cached, whereas standard values in Vary cause NGINX to cache responses taking into account corresponding request header fields. Disabling processing of these headers removes those specific documented behaviors.

Research Method and Limitations

This article was prepared exclusively from the supplied public documentation excerpts for NGINX ngx_http_proxy_module. Material limitations include truncated passages in the primary documentation excerpts, which omit full surrounding directive syntax and complete module context. Additionally, the supplied competitor source text contains only navigation and promotional copy; comparative analysis is therefore strictly limited to the competitor’s observed title (“How To Implement Browser Caching with Nginx’s header Module on Ubuntu 20.04”), which focuses on client-side browser caching headers rather than reverse-proxy caching directives.