Nginx proxy_cache_valid: Status Code Validity Mapping, Header Precedence, and Override Rules

In Nginx reverse-proxy setups, cached response validity is shaped both by local rules configured with proxy_cache_valid and by caching header fields returned by the proxied server. While proxy_cache_valid sets baseline validity times for specified HTTP status codes, upstream response headers take higher priority unless explicitly disabled using proxy_ignore_headers.

Setting Validity Times with proxy_cache_valid

According to the ngx_http_proxy_module and content caching documentation, proxy_cache_valid sets how long responses with specific status codes are considered valid:

proxy_cache_valid 200 302 10m;
proxy_cache_valid 404 1m;

Under this configuration, responses with status codes 200 and 302 are cached for 10 minutes, and responses with code 404 are cached for 1 minute.

If only a caching time is specified without explicit status codes:

proxy_cache_valid 5m;

Nginx caches only 200, 301, and 302 responses for that duration.

To define validity across responses, the any parameter can be specified:

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

Here, any acts as a catch-all validity rule alongside specific status-code directives, setting a 1-minute caching duration for other responses.

Upstream Header Precedence

Caching parameters set directly in the response header have higher priority than setting caching time using proxy_cache_valid. Nginx processes upstream caching instructions as follows:

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

Disabling Upstream Headers with proxy_ignore_headers

Processing of one or more of these response header fields can be disabled using proxy_ignore_headers:

proxy_ignore_headers field ...;

The directive is valid in the http, server, and location contexts with no default value (—). Cache-related fields that can be ignored include X-Accel-Expires, Expires, Cache-Control, Set-Cookie (since version 0.8.44), and Vary (since version 1.7.7).

If an upstream header field is not disabled, it sets response caching parameters or prevents caching. To fully enforce local validity rules configured by proxy_cache_valid, all applicable upstream caching headers—including X-Accel-Expires, Expires, and Cache-Control, as well as Set-Cookie and Vary—must be ignored. If X-Accel-Expires is omitted from proxy_ignore_headers, an upstream server sending that header retains priority and can override local proxy_cache_valid durations or disable caching entirely.

Operational and Security Scoping

Disabling response headers changes Nginx’s caching behavior. In particular, ignoring Set-Cookie or Cache-Control causes Nginx to bypass upstream instructions designed to prevent caching. If applied to responses containing session cookies or personalized user data, cached responses could be served to other clients. Therefore, proxy_ignore_headers should only be applied in contexts where the backend endpoint is verified to return non-personalized, public content.

Configuration Example

The following example defines a shared cache zone in the http block as shown in the Nginx documentation, proxying to an endpoint verified to serve non-personalized public assets while ignoring upstream cache headers:

http {
    proxy_cache_path /data/nginx/cache keys_zone=mycache:10m;

    server {
        listen 8080;

        # Scoped location where backend content is confirmed public and non-personalized
        location /public-assets/ {
            proxy_pass http://localhost:8000;
            proxy_cache mycache;

            # Ignore all upstream caching headers so local directives govern validity
            proxy_ignore_headers X-Accel-Expires Expires Cache-Control Set-Cookie Vary;

            # Baseline status code validity mapping
            proxy_cache_valid 200 302 10m;
            proxy_cache_valid 301 1h;
            proxy_cache_valid 404 1m;
            proxy_cache_valid any 30s;
        }

        # General proxy traffic preserves standard upstream caching headers and cookies
        location / {
            proxy_pass http://localhost:8000;
            proxy_cache mycache;

            proxy_cache_valid 200 302 1m;
        }
    }
}

Research Method and Limitations

This article was prepared directly from the supplied public documentation excerpts for Nginx ngx_http_proxy_module and the NGINX Content Caching Admin Guide. Material limitations apply: competing coverage was unavailable for comparison, and the supplied source excerpts are truncated. As a result, full directive syntax blocks (such as the explicit syntax and context table for proxy_cache_valid) and broader caching behaviors beyond the visible excerpts cannot be verified. This article reflects only the documented syntax, defaults, and priority rules presented in the visible evidence excerpts.

Source references

• nginx.org documentation
• docs.nginx.com documentation