Headers are HTTP's metadata layer. They tell the server who you are, what you accept, and how you encoded the body; they tell the client what came back, how to cache it, and where to go next. This page is a reference, so bookmark it and look things up. The first three tables cover the headers every developer encounters; the last covers the ones specific to Go REST.
Standard request headers
Sent by the client. Most are optional, butHost is required and missingContent-Type on a body breaks most APIs.
Accept
Tells the server what response formats you can read.
application/json, application/xml
Accept-Encoding
Compression formats you accept (gzip, br, zstd).
gzip, deflate, br
Accept-Language
Preferred response language(s); usually ignored by APIs.
en-US, en;q=0.9
Authorization
Credentials. Bearer for API tokens, Basic for username:password, Digest for legacy.
Bearer 4f8c9b...
Cache-Control
On a request: do not return cached responses. On a response: how long the client may cache.
no-cache, max-age=300
Content-Length
Size of the body in bytes. Set automatically by HTTP libraries.
128
Content-Type
Format of the body. Required when sending a body.
application/json
Cookie
All cookies set by previous responses, sent back automatically by the browser.
session=abc; theme=dark
Host
The hostname being requested. Required on HTTP/1.1.
gorest.co.in
If-None-Match
For ETag-based caching. Send the ETag from the last response; server returns 304 if unchanged.
"abc123"
Origin
Where the request came from. Browsers send it on cross-origin requests.
https://app.example.com
Referer
The page that linked to this request. Often used for analytics; can leak URLs.
https://google.com/search
User-Agent
Identifies the client software. Servers use it for analytics and (occasionally) feature gating.
curl/8.4.0
Standard response headers
Sent by the server. Most matter for caching, security, or branching on what to do next.
Cache-Control
Caching rules: max-age, no-store, public, private, no-transform.
public, max-age=300
Content-Type
Format of the response body.
application/json; charset=utf-8
Content-Length
Size of the response body in bytes.
128
Content-Encoding
Compression applied to the body. Client decompresses transparently.
gzip
ETag
Opaque hash of the resource for cache validation.
"abc123"
Expires
Deprecated absolute expiry date. Cache-Control superseded it.
Wed, 21 Oct 2025 07:28:00 GMT
Last-Modified
When the resource was last changed. Pair with If-Modified-Since requests.
Wed, 21 Oct 2025 07:28:00 GMT
Location
On 201 Created or 3xx redirect, where to go next.
/users/4521
Retry-After
On 429 or 503, how long to wait before retrying. Seconds or HTTP-date.
60
Set-Cookie
Asks the client to store a cookie. HttpOnly + Secure + SameSite are essential for sessions.
session=abc; HttpOnly; Secure; SameSite=Lax
Strict-Transport-Security
Tells browsers: only ever talk to me over HTTPS, for this many seconds.
max-age=63072000; includeSubDomains
Vary
Which request headers cause different responses. Critical for shared caches.
Accept, Authorization
WWW-Authenticate
On 401, what auth scheme the server expects.
Bearer realm="api"
CORS headers
Specific to cross-origin browser requests. Servers send them to tell the browser what is allowed; browsers refuse to expose responses if these headers are missing or wrong.
Access-Control-Allow-Origin
Origins allowed to read the response. * for public APIs, exact origin for credentialed.
https://app.example.com
Access-Control-Allow-Methods
Methods allowed on this resource. Returned by pre-flight OPTIONS responses.
GET, POST, PATCH, DELETE
Access-Control-Allow-Headers
Custom request headers the browser may send.
Authorization, Content-Type
Access-Control-Allow-Credentials
Whether the browser may include cookies in the request.
true
Access-Control-Max-Age
How long the browser may cache the pre-flight response (in seconds).
86400
Go REST custom headers
TheX- prefix is the convention for non-standard headers. Go REST exposes pagination, rate-limit budget, and simulation flags this way.
X-Pagination-Total
Total rows matching the filter. On every list response.
2884
X-Pagination-Pages
Number of pages for the current limit.
289
X-Pagination-Page
The page you are on (1-indexed).
1
X-Pagination-Limit
Page size (default 10, max 100 via ?per_page=).
10
X-RateLimit-Limit
Per-token budget for the current minute window (default 90, max 300).
90
X-RateLimit-Remaining
Calls left in the current window.
88
X-RateLimit-Reset
Seconds until the window resets.
47
X-Request-Id
Unique id for the request. Quote it in any bug report.
req_5g7H4Z
X-Simulated-Status
On forced-status simulation, confirms which status was forced.
429
X-Simulated-Delay-Ms
On delay simulation, confirms the delay applied (milliseconds).
1500
Inspecting headers in the browser
Open DevTools, switch to the Network tab, click any request. The "Headers" sub-tab shows everything sent and received. For programmatic access on a Go REST response, use:
fetch(url).then(r => console.log([...r.headers]))
In a terminal,curl -i prints headers along with the body, andcurl -I fetches only headers (HEAD request).
Tips
- Header names are case-insensitive. Most libraries normalise to lowercase on access.
- Custom headers no longer need an
code X-
| prefix per RFC 6648, but in practice everyone still uses it.
- Browsers expose only a small set of response headers to JavaScript by default. To read custom ones (like
code X-RateLimit-Remaining
| ), the server has to allow them via
code Access-Control-Expose-Headers
| .
- The
code Vary
| response header is critical for any cached API response that depends on
code Authorization
| ; skip it and your CDN may serve user A's response to user B.