HTTP Headers Reference

Comprehensive reference for http headers reference covering essential concepts, practical examples, and production best practices.

HTTP Headers Reference

HTTP headers are the metadata that accompany every request and response across the web. They carry authentication credentials, content type information, caching directives, host identification, and custom application signals. Understanding how to view, set, and troubleshoot headers is essential when debugging API integrations, configuring reverse proxies, hardening service security, or diagnosing interoperability failures between clients and servers. This reference collects the practical patterns you’ll use day-to-day, the real commands that produce concrete output, and the silent failure modes that catch teams off guard.

Inspecting headers in transit

When you need to see what headers a client is sending or a server is returning, the most immediate tool is curl in verbose mode. Running curl -v https://example.com produces a full transcript that includes both request and response headers bracketed by > and < markers. For a response-only view, curl -I (or --head) fetches only the headers, which is useful for quickly checking Content-Type, Cache-Control, or WWW-Authenticate without downloading the body.

curl -I https://api.example.com/v1/resource

Typical output includes:

HTTP/2 200 
date: Wed, 12 Mar 2025 18:42:10 GMT
content-type: application/json
via: 1.1 google
age: 123

When debugging redirect chains or proxy-mediated requests, curl -v reveals Location, X-Redirect-By, and hop-by-hop headers that curl -I may suppress. For packet-level capture, tcpdump can filter HTTP traffic. On a macOS or Linux workstation:

tcpdump -i en0 port 80 or port 443 -A -s 0 -c 5

The -A flag prints payload as ASCII, making headers legible within the stream. In containerized environments, kubectl exec can forward tcpdump or curl into a pod, but the output format remains the same.

For structured parsing, pipe curl -s into jq or grep. For example, to extract the X-Rate-Limit-Remaining header:

curl -s https://api.example.com/v1/resource -D - | grep -i "x-rate-limit-remaining"

The -D - flag writes headers to stdout alongside the body, and grep isolates the line of interest. Alternatively, curl -s -o /dev/null -w "%{header_name}" can output a single header value, but this only works for built-in curl variables; custom headers require the -D - approach.

Setting and customizing request headers

Adding a header to an outbound request is done with curl -H. This flag accepts a Name: Value pair and appends it to the request. Multiple headers are stacked by repeating the flag:

curl -H "X-Request-ID: $(uuidgen)" -H "Accept: application/vnd.api+vjson" https://api.example.com/v1/resource

Authentication is a common header-setting use case. Basic auth is triggered with --user or -u, which internally adds an Authorization: Basic <base64> header:

curl -u api-user:api-pass https://api.example.com/v1/resource

For digest auth, curl uses --digest, which adds the appropriate Authorization challenge-response flow. When an API expects a custom token in a header named Authorization, the pattern is identical:

curl -H "Authorization: Bearer $TOKEN" https://api.example.com/v1/resource

Some services expect idempotency keys as a client-supplied header. The standard pattern is:

curl -H "Idempotency-Key: 3f6a1e8d-9a2b-4c7d-8e3f-a1b2c3d4e5f6" -X POST https://api.example.com/v1/orders

If the key is already stored in an environment variable, the shell expands it at invocation time, as shown above.

When testing webhook signatures, you may need to send a User-Agent that mimics a specific client. curl lets you override this:

curl -H "User-Agent: my-integration/1.0" https://example.com/webhook

Browsers and HTTP clients often set Accept-Encoding to request gzip or deflate response compression. curl respects this automatically, but you can explicitly request a coding:

curl -H "Accept-Encoding: gzip, deflate" -H "Accept: */*" https://example.com/large-resource

The server responds with a Content-Encoding header (e.g., gzip) and the body arrives compressed. curl decompresses transparently, but the Content-Encoding header remains visible in -v output.

Interpreting response headers

Response headers tell you how to handle the body, whether caching is permitted, and whether access is authorized. The Content-Type header determines how the client parses the payload; a mismatch (e.g., text/html returned for a requested application/json) typically causes a parsing error in API clients. The Content-Length header indicates body size; its absence with Transfer-Encoding: chunked means the stream must be consumed until the terminating chunk.

Caching directives live in Cache-Control. A value of public, max-age=3600 means the response may be cached by any cache for one hour. no-store prohibits caching entirely, and no-cache requires revalidation on each use. When a client sends If-Modified-Since or If-None-Match, the server may respond with 304 Not Modified, eliminating the body transfer. curl will display this as:

HTTP/2 304 
date: Wed, 12 Mar 2025 18:50:00 GMT
cache-control: max-age=0, must-revalidate

Rate-limiting information is frequently exposed via custom headers such as X-Rate-Limit-Limit, X-Rate-Limit-Remaining, and X-Rate-Limit-Reset. These are not part of the HTTP standard but are ubiquitous in API platforms. Their values are integers; remaining decrementing to 0 typically triggers a 429 Too Many Requests response with a Retry-After header specifying the wait time in seconds.

Security headers such as Strict-Transport-Security, X-Content-Type-Options, and X-Frame-Options govern browser behavior. Strict-Transport-Security: max-age=31536000; includeSubDomains forces HTTPS for the domain and subdomains for the stated period. Missing or misconfigured security headers are a common root cause of mixed-content warnings and clickjacking vulnerabilities.

Server-side header manipulation

Reverse proxies and web servers alter or inject headers as requests pass through. The typical mechanism accepts a mapping between a configuration value and an outgoing HTTP header name, with the value sourced from a literal, an environment variable, or a request attribute. Many implementations support conditional injection—adding a header only when a certain path, method, or query parameter is present—but the exact syntax is product-specific. A generic pattern looks like:

> “Configure the proxy to map a directive’s value to an Outbound-Header entry, where the header name and value may reference request context or environment variables. The directive accepts the header name as a literal string and the value as either a static string or a interpolation of request-scoped data.”

When debugging downstream header issues, curl -v against the upstream service versus the proxy reveals which headers are stripped, added, or modified at the edge. A common silent failure is a proxy removing Authorization headers for security or compliance reasons, causing the upstream to return 401 Unauthorized with a WWW-Authenticate challenge. Another is a proxy adding X-Forwarded-For with the client IP, which upstream services use for rate limiting or geo-routing; if the proxy is misconfigured, the header may contain unknown or the client’s proxy IP instead of the true origin.

Sharp edges and production failure modes

Case sensitivity. The HTTP spec treats header names as case-insensitive, but not all implementations enforce this uniformly. A client sending Content-Type may find the server logs it as content-type, and downstream parsing that expects exact casing can miss the value. Conversely, some proxies normalize to lowercase on inbound and uppercase on outbound, causing mismatches in signed request verification.

Duplicate headers. The spec allows multiple headers with the same name, but handling varies. Some servers concatenate values with a comma; others use only the first or last occurrence. When a client sends two X-Request-ID headers, the receiving service may log only one, and which one depends on the implementation. This is a frequent source of correlation-id loss in distributed tracing.

Header size limits. Proxies and servers often impose maximum header field sizes. Exceeding them results in a 431 Request Header Fields Too Large response. The threshold is implementation-defined; some APIs enforce a few kilobytes, while others allow tens of kilobytes. When a request includes many custom headers for tracing or audit, the total size can accidentally cross the limit, causing the entire request to be rejected without a clear “which header” indication.

Proxy stripping of hop-by-hop headers. Headers marked as hop-by-hop in RFC 7230 (e.g., Connection, Keep-Alive, Transfer-Encoding, Upgrade) are supposed to be stripped by proxies before forwarding. If a proxy fails to strip them, or if a client incorrectly includes them in a 100-continue expectation, the downstream service may attempt to interpret them as application data, leading to malformed payload processing.

Environment variable leakage. When server configurations reference environment variables to populate header values, improper quoting or missing variables can result in headers like Authorization: Bearer (empty token) or X-Request-ID: ${undefined}. In containerized workloads, missing env vars may cause the server to fail startup or substitute an empty string, depending on the configuration framework.

Time-sensitive headers. Headers such as Date, Expires, and Cache-Control max-age are time-dependent. Clock skew between client and server can cause If-Modified-Since comparisons to fail unexpectedly, resulting in unnecessary 200 OK responses instead of 304 Not Modified, inflating bandwidth usage and masking caching effectiveness.

Quick checklist

This page was rewritten on 26 October 2026. It replaced a templated version that was not specific to its own title. How these pages are written and checked. If anything here is wrong, tell us at hello@thegarnetwiki.com and we will correct it.