Request and Response Headers

Metadata, not payload

Headers are key-value lines that travel alongside the body of every request and response. They carry metadata — who you are, what format you are sending, what you would like back, how the result may be cached — without cluttering the payload itself with that bookkeeping.

A request body might be a JSON document; the headers describe that document and the conditions surrounding it. It helps to think of the body as the contents of an envelope and the headers as everything written on the outside. Header names are case-insensitive, so Content-Type and content-type refer to the same field, though most tools and documentation use the familiar capitalised form by convention. Your own code should compare them without regard to case.

Headers you send

On the request side, a few headers do most of the work. Authorization carries your credentials, typically a bearer token. Content-Type declares the format of the body you are sending so the server knows how to read it. Accept states which formats you are able to handle in the reply.

POST /v1/messages HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json
Accept: application/json

Custom headers, often prefixed with the vendor's name, may switch on optional behaviour such as supplying an idempotency key or selecting a beta feature. The documentation for each endpoint lists exactly which ones it understands, so it is worth scanning that list rather than assuming a header you used elsewhere will be honoured here.

Content negotiation

Content negotiation is the polite conversation in which the client says what it wants and the server says what it actually sent. You ask with Accept: application/json; the server answers with Content-Type: application/json so you know precisely how to interpret the body you received.

When the two cannot be reconciled — you request JSON but the endpoint is only able to return some other format — the server may respond with 406 Not Acceptable rather than guessing. Matching your Accept header to what the API genuinely supports keeps that conversation smooth and avoids a confusing rejection that has nothing to do with your data or your credentials. Most JSON APIs make this trivial, but it matters the moment alternatives like CSV enter the picture.

Headers you read

Responses carry valuable headers too, and ignoring them throws away free information. Location points at a newly created resource. Content-Length and Content-Type describe the body so you can size and parse it. Rate-limit headers reveal how many calls you have left in the current window, and caching headers such as ETag and Cache-Control tell you whether and for how long a response can be reused.

Reading these rather than discarding them turns guesswork into informed behaviour. You can slow down before you actually hit a limit, skip a redundant re-download when nothing has changed, and follow a freshly created resource to its real address — all without any extra round trips.

Practical habits

Set Authorization, Content-Type, and Accept deliberately on every call rather than relying on a client default you have not checked. When debugging, log the response headers as well as the body — they very often explain a failure that the body alone does not, especially around auth and caching. Treat header names case-insensitively in your own comparisons so you never miss one because of capitalisation.

For how the content headers in particular interact with character encodings and compression, read content types and encoding, which picks up exactly where this leaves off and covers the format-related headers in depth.