HTTP Headers in API Development: Structure and Examples

When an API returns 401 despite a valid token, or cached content refuses to update after deployment, the cause is almost always a header. Knowing how to read and modify HTTP headers turns these frustrating issues into quick fixes.

What Is an HTTP Header?

An HTTP header is a key-value pair transmitted between client and server in every HTTP request and HTTP response, including API calls. Headers carry metadata that controls authentication, content types, caching, and security policies. Without headers, the server cannot determine the format of incoming data, and the client cannot interpret the response.

HTTP Header Format and Structure

Every HTTP header follows the same structure: a case-insensitive name, followed by a colon, optional whitespace, and the value. The header ends at the next line break (CRLF).

Header-Name: header-value

For example:

Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
Cache-Control: max-age=3600, public

Header names are case-insensitive per RFC 7230—Content-Type, content-type, and CONTENT-TYPE are equivalent. Values, however, are often case-sensitive depending on the header. In API integrations, this detail matters when signatures or auth schemes depend on exact value formatting.

In HTTP/2 and HTTP/3, headers use HPACK compression. Pseudo-headers prefixed with a colon (:method, :path, :status) replace the HTTP/1.x request line.

Types of HTTP Headers

HTTP headers fall into four categories based on where they apply and what they describe.

Headers are also classified by how intermediaries handle them. End-to-end headers must pass unchanged to the final recipient. Hop-by-hop headers (like Connection and Keep-Alive) apply only to the immediate connection and must not be forwarded by proxies.

Common HTTP Headers in API Development

This section covers the most frequently encountered headers, grouped by function.

Authentication Headers

Authorization carries client credentials. WWW-Authenticate is the server's challenge on auth failure. Common schemes: Basic, Bearer (OAuth), and Digest.

Authorization: Bearer <token>
WWW-Authenticate: Bearer realm="api"

Content Negotiation Headers

Accept specifies which media types the client handles. Content-Type declares the actual body media type. A mismatch causes parsing failures.

Accept: application/json, text/html;q=0.9
Content-Type: application/json; charset=utf-8

Caching Headers

Cache-Control is the primary caching directive. ETag provides a version identifier for conditional requests. Last-Modified enables time-based validation.

Cache-Control: max-age=86400, must-revalidate
ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"

Common issue: a client receives stale data despite server changes. The cause is often max-age set too high or a CDN ignoring no-cache.

CORS Headers

CORS headers control which origins can access resources. When a browser blocks a fetch with a CORS error, the response lacks the required Access-Control-Allow-Origin header.

Access-Control-Allow-Origin: https://example.com
Access-Control-Allow-Methods: GET, POST, PUT
Access-Control-Allow-Headers: Content-Type, Authorization

Preflight requests (OPTIONS) are sent before actual requests for non-simple methods or custom headers.

Security Headers

Security headers protect web applications against common vulnerabilities.

Cookie Headers

Set-Cookie creates a cookie on the client. Cookie sends stored cookies back. Session management and user preferences rely on these headers.

Set-Cookie: session=abc123; Path=/; HttpOnly; Secure; SameSite=Strict

How to View and Debug HTTP Headers

When an API returns unexpected results or a request fails silently, inspecting the actual headers sent and received is the irst step in debugging.

1. Browser Developer Tools: Open the Network tab, select a request, and view the Headers pane. Works only for browser traffic.
2. curl: Use curl -v for verbose output including headers, or curl -I to fetch headers only.
3. HTTP Sniffer: For traffic from desktop applications, background services, or processes that do not respect system proxy settings, a network-level tool is required.

HTTP Debugger captures HTTP and HTTPS traffic system-wide without proxy configuration. It displays headers for any Windows application—including .NET, Java, and C++ traffic that bypasses browser tools. The HTTP Modifier feature lets you add, remove, or change headers on the fly to test different scenarios.

Common Header-Related Problems

Many production bugs trace back to header misconfiguration.

CORS Failures

The console shows "No 'Access-Control-Allow-Origin' header is present." The server must return this header with the requesting origin or *. For credentialed requests, the origin must be explicit—* is not allowed with credentials.

Authentication Rejected Despite Valid Credentials

A 401 response on a valid token. Check whether the Authorization header is actually being sent (CORS preflight may strip it), whether the scheme matches expectations (Bearer vs. Basic), and if the token format is correct.

Stale Cache Content

The server returns updated data, but clients see old content. Verify Cache-Control values, check CDN layers that may ignore origin headers, and confirm ETag or Last-Modified validation.

Custom Headers and Naming Conventions

Applications define custom headers for API versioning, request tracing, idempotency keys, or feature flags. The X- prefix was historically used for non-standard headers but is now deprecated per RFC 6648. Use descriptive names without the prefix.

Api-Version: 2024-01
Trace-Id: 550e8400-e29b-41d4-a716-446655440000

HTTP Headers FAQ

• What is the maximum size of an HTTP header? HTTP/1.1 defines no limit, but servers impose one. Apache defaults to 8KB for all headers combined. Exceeding this returns a 431 status.
• Are HTTP header names case-sensitive? No. Header names are case-insensitive per RFC 7230. Content-Type and content-type are treated identically.
• What is the difference between headers and cookies? Cookies are a specific type of header. Set-Cookie is a response header that instructs the client to store data. Cookie is a request header that sends stored values back to the server.
• How do I add custom headers to a request? In JavaScript, use the headers option in fetch(). In curl, use -H. Server-side, set headers before sending the body.
• Why does my custom header disappear in the browser? CORS may be stripping it. Non-simple headers require the server to list them in the Access-Control-Allow-Headers and Access-Control-Expose-Headers headers.