What Is the `Vary` Header? A Simple Guide for Developers

When you build web apps that use caching-CDNs, reverse proxies, or even browser cache, the Vary header becomes one of, your best friends. It tells caches how to treat different versions of the same URL, so users always get the correct response.

Let’s break it down.

What Does the Vary Header Do?

A cache normally stores one version of a URL. But sometimes, your server returns different responses depending on headers like:

• Accept-Encoding (gzip vs br)
• User-Agent (mobile vs desktop)
• Accept-Language (English vs Turkish)
• Authorization (logged-in vs guest)
• Origin (CORS decisions)

The Vary header says:

“If this header changes, treat the response as a separate cache entry.”

Example:

Vary: Accept-Encoding

This tells the cache: “Store a gzip version and a br version separately, don’t mix them.”

Why the Vary Header Matters

1. Prevents Serving Wrong Content

Imagine your server returns Turkish content only when Accept-Language: tr is sent.

Without Vary: Accept-Language, the first cached TR version could be served to English users too. Disaster.

2. Helps with Device-Specific Views

If you send different HTML for mobile vs desktop:

Vary: User-Agent

Without it, desktop users might get mobile HTML.

3. Required for Some Security Features

Some servers vary behavior based on Origin. Then you must add:

Vary: Origin

Otherwise a cached response may incorrectly allow or deny CORS requests.

Common Vary Header Use Cases

Gzip / Brotli Compression

Most common one:

Vary: Accept-Encoding

Needed so caches don't serve Brotli to browsers that don't support it.

Localization

Vary: Accept-Language

For language-specific pages.

CORS

Vary: Origin

If you send dynamic CORS headers.

Cookies / Auth

Be careful. Vary: Cookie can kill cache efficiency because cookies are all unique.

But it's valid when you must split cached pages between logged-in and guest users.

Examples

Nginx

add_header Vary Accept-Encoding;

Express.js

app.use((req, res, next) => {
  res.set("Vary", "Accept-Encoding");
  next();
});

Go (net/http)

w.Header().Add("Vary", "Accept-Encoding")

Best Practices

• Keep Vary headers short. Don’t add unnecessary variations.
• Avoid Vary: Cookie unless absolutely required.
• Always set Vary: Accept-Encoding if you use gzip/brotli.
• If you use dynamic CORS, don’t forget Vary: Origin.

Conclusion

The Vary header is tiny but powerful. It keeps your caching layer smart, prevents content mismatches, and ensures users get the right version of your pages.

Use it correctly, and your app becomes faster and more reliable. Forget it, and you’ll chase weird bugs for days.

Album of the blog: