HTTP Headers.

The entire caching policy in one field: how long a response stays fresh, who is allowed to store it, and what has to happen once it goes stale.

The same word means different things on a request and on a response. Every directive is spelled out in the next table.

Seconds this response has already spent sitting in caches. Shared caches add it; clients subtract it from max-age to get the remaining freshness.

An Age that climbs past your max-age without a revalidation is a misconfigured CDN, not a fast one.

An absolute date after which the response is stale. The HTTP/1.0 way of saying max-age.

Ignored whenever Cache-Control max-age or s-maxage is present. Expires: 0 is the widespread non-conforming way to say 'already stale' — use no-cache instead.

An opaque version tag for this exact representation. The client hands it back to ask whether it is still current.

A W/ prefix marks it weak: fine for cache revalidation, useless for If-Match concurrency. Gzip and identity variants must not share a strong ETag.

When the representation last changed. The weaker validator, for when you have no ETag.

One-second resolution, so two edits inside the same second are invisible. Also what caches use for heuristic freshness when you send no explicit lifetime.

Revalidation: send the body only if the ETag is none of these. A match gets a 304 with no body.

Wins over If-Modified-Since when both are sent. Uses weak comparison, so W/ tags do match.

Date-based revalidation: send the body only if it changed after this timestamp.

Only meaningful on GET and HEAD, and ignored entirely when If-None-Match is present.

Names the request headers that were used to select this representation. In other words: the rest of the cache key.

Omit one and a shared cache will happily hand a Brotli body to a client that cannot decode it, or one tenant's CORS headers to another. Vary: * means never reusable.

Caching policy aimed at CDNs only. They obey it in place of Cache-Control; browsers ignore it completely.

RFC 9213 targeted cache control. The clean way to cache hard at the edge and barely at all in the browser, without the usual s-maxage contortions.

The pre-RFC vendor spelling of the same idea, still honoured by Varnish, Fastly and friends.

How each cache in the path handled the request: hit or miss, remaining TTL, which node answered.

RFC 9211. Standardises the pile of X-Cache headers every CDN invented separately.

The HTTP/1.0 ancestor of Cache-Control, with one useful value.

Only ever defined for requests. Sending it on a response does nothing except make your headers longer.

Free-text notes about staleness and transformations.

Obsoleted by RFC 9111. Nothing generates it and nothing reads it.

On a response: fresh for N seconds, counted from when the origin generated it — not from when you received it. On a request: I will not accept anything older than N seconds.

Age is what makes the origin-relative part work. A response that spent 500s in a CDN has 100s of freshness left, not 600.

Freshness for shared caches only — CDN, reverse proxy. Overrides both max-age and Expires for them, and leaves the browser on max-age.

Also implies proxy-revalidate, so a shared cache may not serve it stale once it expires.

Store it, but never reuse it without asking the origin first. This is a revalidation rule, not a ban on caching.

A 304 costs one small round-trip and no body. This is usually the right answer for HTML.

Do not write this to any storage, anywhere, in any form. The only directive that actually means do not cache.

Correct for responses carrying credentials or personal data. Add private and no-cache too if you need to defeat ancient, buggy intermediaries.

Only a single-user cache — the browser — may store this. Shared caches must not.

Not a security control. It is a request to well-behaved caches, and the body still passes in cleartext through anything terminating your TLS.

Storable even in the cases where it normally would not be — most usefully, when the request carried an Authorization header.

Redundant on an ordinary unauthenticated GET; that is already cacheable. Adding it out of habit to authenticated responses is how private data lands in a CDN.

Once stale, it must not be served again until the origin confirms it.

If the origin is unreachable the cache must return a 504 rather than a stale body. That is a correctness choice, and it costs you availability.

must-revalidate, but binding only on shared caches.

The body at this URL will never change, so do not revalidate it even when the user hits reload.

Only safe on content-hashed URLs like app.7f3c1d.js. Put it on /app.js and you will serve last week's bundle to people who have no way to fix it.

For N seconds past expiry, serve the stale copy immediately and refresh it in the background.

The largest latency win available in this whole field, for one line of config. The cost is that some users see a response up to N seconds out of date.

If the origin errors or times out, keep serving the stale copy for up to N seconds instead of passing the failure through.

Free availability during an incident, and nothing to build. Note that must-revalidate cancels it.

Intermediaries must not recompress images, minify, or otherwise rewrite the payload.

Worth setting on anything signed, checksummed, or byte-exact — and on images where a carrier proxy would otherwise degrade them.

Store this only if the cache understands the caching rules for its status code.

Newer caches honour must-understand and may store; older ones see the no-store beside it and skip. A forward-compatibility trick, not an everyday directive.

Return the cached copy or a 504. Do not touch the network.

How offline modes and some service workers ask for a strictly local answer.

I will accept a response that has been stale for up to N seconds.

I want a response that will still be fresh for at least another N seconds.

Only perform this write if the resource still carries one of these ETags. HTTP's compare-and-swap.

A mismatch returns 412 Precondition Failed. Strong comparison, so a W/ tag never matches. This is how you stop two tabs silently overwriting each other.

The dated version: only write if nothing has changed since this timestamp.

Weaker than If-Match because of the one-second clock. Prefer ETags whenever you can generate them.

Ask for specific byte ranges instead of the whole body.

Answered with 206 and a Content-Range, or 416 if the range makes no sense. Multi-range requests are legal and mostly a denial-of-service vector — cap them.

Advertises that range requests work here. Two values in practice: bytes, or none.

Without it, well-behaved download managers will not attempt a resume.

On a 206: which bytes these are, and how large the whole thing is.

An unsatisfiable range gets a 416 plus Content-Range: bytes */7340032 so the client learns the real size.

Send the range only if the resource has not changed; otherwise send the whole thing.

Saves a round-trip on a resumed download: you get a 206 if the file is untouched, a plain 200 if it is not, and never a corrupted splice.

Media types the client can handle, with q-weights expressing preference.

If nothing matches, the honest answer is 406. Most APIs ignore this and always return JSON, which is fine — just do not also advertise negotiation you do not do.

Compression formats the client understands.

The reason Vary: Accept-Encoding is mandatory on anything you compress at the origin.

Preferred human languages, weighted.

Serving different copy per language without Vary: Accept-Language is the classic way to show a French page to an English visitor straight out of the cache.

Character encodings the client accepts.

Deprecated in RFC 9110. Browsers stopped sending it years ago, and everything is UTF-8.

The media type of the body, plus parameters such as charset and multipart boundary.

Always send charset on text types. A JSON body sent with no Content-Type is the single most common cause of a mysterious 415.

How the body was compressed. End-to-end: it stays compressed until the client decodes it.

Not the same thing as Transfer-Encoding, which is per-hop and can be undone by any proxy on the path.

Which language the body is in — the answer to Accept-Language, and one of the seven headers CORS exposes by default.

Body size in bytes.

Sending Content-Length and Transfer-Encoding: chunked on the same HTTP/1.1 message is the foundation of request smuggling. A front end should reject that message, not pick a winner.

Render inline or download, and what to call the file.

For non-ASCII names use the filename* form with UTF-8 percent-encoding. Sanitise it either way — an unescaped filename is a header-injection hole.

The direct URL of the representation you just received, when it differs from the URL you asked for.

Not Location, and it redirects nothing. Mixing the two up produces bugs that survive code review because the names look alike.

A checksum of the body, carried as a structured field.

RFC 9530, replacing the old Digest header. Useful on webhooks and uploads; compare in constant time when it feeds a signature check.

How the message body was framed on this hop — in practice, chunked.

HTTP/1.1 only. Forbidden in HTTP/2 and HTTP/3, which do their own framing.

Transfer codings the client accepts on this hop, including trailer fields.

Hop-by-hop, and one of the fields a smuggling-aware proxy should normalise rather than forward blindly.

The methods this resource supports. Required on a 405.

A 405 without Allow leaves the caller guessing, which defeats the entire point of the status code.

Where to go next: the redirect target on a 3xx, or the URL of the thing you just created on a 201.

A 201 without a Location is a half-finished API. So is a 202 that gives you nowhere to poll.

Typed relations to other URLs: pagination, preload, canonical, API discovery.

Paired with a 103 Early Hints response, rel=preload buys you asset fetches while the origin is still assembling the real answer.

Which origin the request came from. The browser sets it and page JavaScript cannot change it.

Sent on every cross-origin request and on same-origin POST too. It can legitimately be the literal string null — sandboxed iframes, some redirects — so never let null pass an allowlist check.

On a preflight: the method the real request is about to use.

Only ever appears on the OPTIONS preflight, never on the request that follows it.

On a preflight: the non-safelisted headers the real request wants to send.

This is why adding one custom header to a fetch call suddenly doubles your request count.

The single origin allowed to read this response — or the wildcard.

You may send one origin, never a list. Check the request Origin against your allowlist, echo it back, and add Vary: Origin the moment you do.

Preflight answer: which methods are permitted.

Only read on the preflight response. Sending it on real responses is harmless noise.

Preflight answer: which request headers are permitted.

The wildcard does not cover Authorization. If your clients send a bearer token, you have to name that header explicitly or the preflight fails.

Lets the browser attach cookies and expose the response when the request used credentials: include.

Illegal alongside a wildcard origin. Turn credentials on and every wildcard in the CORS set stops behaving as a wildcard.

Which response headers JavaScript is allowed to read.

Without it, fetch sees only seven safelisted headers: Cache-Control, Content-Language, Content-Length, Content-Type, Expires, Last-Modified, Pragma. Your custom header is visible in DevTools and absent in code.

How long the browser may cache this preflight result, in seconds.

The default is 5 seconds and browsers clamp the maximum — Chromium at 7200, Firefox at 86400. Anything larger is silently reduced, not honoured.

Lets a cross-origin page read detailed timings and Server-Timing for this resource.

Nothing to do with access control; it only unlocks measurement. Without it, cross-origin Resource Timing entries are mostly zeroes.

Forces HTTPS for this host for max-age seconds, with no click-through past certificate errors.

Ignored over plain HTTP by design. includeSubDomains covers hosts you forgot about; preload bakes you into browser binaries and is genuinely hard to undo. Ship a short max-age first.

An allowlist of where scripts, styles, images, frames and connections are allowed to come from.

The nonce or hash on script-src is the part that actually stops XSS. Leave 'unsafe-inline' in and the policy is decoration. Add base-uri or an injected base tag reroutes every relative script URL.

The same policy, enforced nowhere, violations reported.

Always run a new policy here first. Real traffic breaks a CSP in ways staging never will — analytics snippets, injected extensions, a marketing tag someone added last quarter.

Stops the browser guessing a media type that disagrees with your Content-Type.

One value, no downside, kills a whole class of upload-to-XSS. It also makes browsers refuse scripts and stylesheets served with the wrong type, which is how you find your broken MIME config.

How much of the current URL is attached to outgoing requests.

That value is already the browser default. Set it anyway, and use no-referrer on any page whose URL contains a token, an invite code, or a customer id.

Which browser capabilities this page and its frames may use.

An empty allowlist disables the feature outright. Replaces Feature-Policy, which used different syntax and no longer ships.

Blocks framing of this page. Two usable values: DENY, SAMEORIGIN.

Superseded by CSP frame-ancestors, which takes an origin list and wins when both are present in a modern browser. ALLOW-FROM was never implemented widely and is gone.

Severs the window.opener link between your document and cross-origin ones.

Half of the cross-origin isolation pair, and worth setting on its own — it closes a family of tab-napping and cross-window probing attacks.

Requires every subresource to opt in to being embedded here.

The other half. COOP plus COEP gives you crossOriginIsolated, which SharedArrayBuffer and high-resolution timers require. It will also break every third-party embed that does not send CORP.

Declares who is allowed to embed this resource at all.

Set cross-origin on public CDN assets or you break every isolated site embedding them. Set same-origin on anything private and you get a cheap defence against speculative-execution style leaks.

Names the URLs that CSP, COOP, deprecation and crash reports get posted to.

The structured-field replacement for Report-To. Referenced by name from the report-to directive inside a CSP.

Tells the browser to wipe cookies, storage or cache for this origin.

The values are quoted strings — unquoted is a silent no-op. Send it on logout. HTTPS only, and cache clearing support varies.

Toggled a legacy browser XSS auditor.

The auditors were removed years ago and were themselves exploitable. If a compliance scanner insists, send 0. Otherwise delete it and write a real CSP.

Relationship between the requesting page and the target: same-origin, same-site, cross-site or none.

Browser-set and unforgeable from JavaScript, which makes the Sec-Fetch family a cheap, cookie-free CSRF check that costs one string comparison.

How the request was made: navigate, cors, no-cors, same-origin or websocket.

A state-changing POST arriving with mode navigate and site cross-site is a form submission from somebody else's page.

What the response will be used for: document, script, image, style, empty, and so on.

Reject a request whose Dest is script but whose URL is your JSON API and you have closed a whole category of cross-site data leak.

Present only when a navigation came from a real user gesture.

Only sent on navigations, and only ever with that one value.

Credentials for the target resource.

Its presence makes the response uncacheable by shared caches unless you explicitly say public or s-maxage. It is also the header the CORS wildcard refuses to cover.

The challenge that must accompany a 401: which scheme, which realm, and usually why the last attempt failed.

A 401 without this header is malformed. It is also the difference between a client that knows to refresh its token and one that retries the same dead credential forever.

Credentials for the proxy in front of you, not for the origin.

Hop-by-hop: the proxy consumes it and must not forward it upstream.

The 407 equivalent of WWW-Authenticate.

Extra data at the end of a successful authenticated exchange — a next nonce, mutual-auth proof.

Digest and mutual schemes only. You will never write it by hand for a bearer-token API.

Every cookie whose domain, path and flags match, concatenated, with no indication of who set which.

Cookies ignore ports and largely ignore scheme, so localhost:3000 and localhost:8080 share one jar. That is a debugging trap, not a feature.

Sets one cookie, with its lifetime and its security flags.

The one header that legitimately repeats — never join them with commas. SameSite=Lax by default; SameSite=None is only valid with Secure. The __Host- prefix forces Secure, Path=/ and no Domain, and is the strongest cookie you can ship.

Current quota state as a structured field: which policy, how many requests remain, seconds until reset.

From the IETF ratelimit-headers work. The field shape changed between drafts, so check the revision your library implements before you promise anything to clients.

The policy itself — quota and window length — so a client can pace itself instead of probing for the wall.

Send this alongside RateLimit and a well-written client never needs to hit a 429 at all.

Earlier-draft field: the quota for the current window.

Superseded by RateLimit-Policy, but this triplet is still what most shipping implementations emit.

Earlier-draft field: requests left in the current window.

Earlier-draft field: seconds until the window resets.

Delta-seconds here — unlike the X- version, which is where most of the confusion comes from.

The de-facto original. Quota for the window.

Requests left in the window.

Expose it through CORS or your browser clients cannot read it and will keep guessing.

When the window resets — and nobody agrees on the unit.

GitHub sends a Unix timestamp in seconds. Plenty of others send seconds remaining. A client that guesses wrong either hammers you immediately or sleeps for fifty-six years.

How long to wait before trying again — delta-seconds or an HTTP-date.

Valid on 429, on 503, and on a 3xx. Sending it on a 503 during a bad deploy turns a retry storm into an orderly queue, which is the cheapest availability win in this table.

The chain of client IPs, appended to by each proxy: original client first, nearest proxy last.

Anyone can send this header. Count in from the right through exactly as many hops as you actually operate, and never read element zero blindly.

The scheme the client originally used, before your load balancer terminated TLS.

Without it your app believes every request is plain HTTP and starts emitting http:// redirects that loop forever behind the balancer.

The Host the client originally asked for.

Build absolute URLs from this without an allowlist and you have host-header injection — including password-reset links that point at somebody else's domain.

The port on the original client connection.

The standardised version of all of the above, in one field.

RFC 7239. Handles IPv6 and obfuscated identifiers properly, which X-Forwarded-For never did. Support is patchy, so most stacks emit both and trust neither by default.

A single client IP. Nginx's convention.

Whatever the closest proxy decided the client was. Exactly as forgeable as X-Forwarded-For if that proxy does not overwrite it on every request.

Each proxy and cache that handled the message.

The standard hop record, and a good way to discover an intermediary nobody told you about.

Which virtual host on this connection the request is for. Mandatory in HTTP/1.1.

HTTP/2 and HTTP/3 use the :authority pseudo-header instead. Either way it is caller-controlled input — validate it against known hosts before it reaches routing or URL generation.

Per-hop connection control, plus the list of other fields that are hop-by-hop.

Forbidden in HTTP/2 and HTTP/3, where a connection-specific field is a protocol error rather than a nuisance.

Idle timeout and request cap for a persistent HTTP/1.1 connection.

Set your client idle timeout below the server's or you will race it and see phantom connection resets under load.

Ask to switch protocols on this connection — in practice, WebSocket.

Needs Connection: Upgrade beside it. Over HTTP/2 the mechanism is extended CONNECT instead, so a 101 never appears there.

One defined value: ask the server to approve the headers before you send a large body.

Saves uploading a gigabyte that a 413 was always going to reject. Some proxies mishandle it, which is why curl gives you an option to switch it off.

Marks a request that arrived in TLS 1.3 0-RTT data and is therefore replayable.

If the request is not idempotent, answer 425 Too Early and let the client resend on a fully established connection.

Advertises the same service on another protocol or endpoint — how browsers discover HTTP/3.

Cached for ma seconds. It is the reason your first page load was HTTP/2 and the second was QUIC.

When the response was generated at the origin. Caches do all their freshness arithmetic against it.

A server with a badly skewed clock breaks Age and Expires maths in every cache along the path, and the symptom looks nothing like a clock problem.

The origin software.

Free reconnaissance for anyone scanning you. Strip the version number at minimum — no client has ever needed it.

Client software string, historically a stack of compatibility lies.

Frozen and reduced in Chromium. Do not branch behaviour on it — use feature detection, or client hints if you genuinely need the device.

The page that linked here. The spelling is a 1996 typo baked permanently into the standard.

Trimmed to the origin cross-site by default. Never use it for authorisation, and never put secrets in URLs that other sites can link to.

Server-side timings surfaced to the browser and to the Resource Timing API.

Cross-origin it is invisible unless you also send Timing-Allow-Origin. Real backend telemetry inside the browser's own waterfall, for the cost of one header.

W3C Trace Context: trace id, parent span id and sampling flag for distributed tracing.

Propagate it verbatim through every hop, including queue messages. Dropping it in one service is how a single trace ends up as two unrelated ones.

Vendor-specific tracing state travelling beside traceparent.

A correlation id you can grep for across every service and every log line.

Generate it at the edge when the client did not send one, echo it on the response, and put it in every error body. Not standard, universally understood.

Indexing rules for crawlers, for responses that cannot carry a meta tag.

The only way to keep a PDF, a JSON endpoint, or an entire staging environment out of an index.

Request urgency, and whether the response should be delivered incrementally.

RFC 9218. Urgency runs 0 to 7, defaults to 3, and lower is more urgent. Servers may honour it or ignore it entirely.