Accept Header

Overview

Meaning and scope

Accept Header is an HTTP request header that tells a server which response media types the client can understand and may rank them by preference. Accept describes desired response formats, whereas Content-Type describes the representation actually sent in a request or response body.

Mechanism and operation

The Accept Header owner should publish stable error semantics and guidance on whether correction, retry, status lookup, or escalation is appropriate. A production implementation should publish supported media types, parse quality values correctly, return a clear not-acceptable response when negotiation fails, and test default behavior across API versions. A successful transport result from Accept Header should not be interpreted beyond the exact API state documented by the provider. Useful measures include media-type negotiation failures, 406 responses, fallback usage, client-version distribution, and parsing errors by response type. Changes to Accept Header should be checked against older clients, stored payloads, enum growth, default behavior, and retry assumptions.

Practical payment example

A client requests JSON using an Accept header, while the server returns an explicit media type and rejects unsupported representations.

Operational checks

Observability for Accept Header should record operation, version, principal, request ID, latency, retry count, error code, and final state without exposing secrets. Testing Accept Header should cover malformed input, denied access, rate limits, timeouts, duplicates, asynchronous completion, and version changes. Data handled by Accept Header should use documented types, units, timestamp rules, nullable fields, and enum behavior to prevent silent interpretation errors.

Distinctions and limits

The principal risks include unexpected response formats, silent fallback, broken deserialization, cache variation errors, incompatible clients, and security filters applied to the wrong representation. The Accept Header contract should define identifiers, validation, authorization, status semantics, errors, limits, and version behavior at the same boundary.

Related reading

Related definitions: Content-Type Header, Backward-Compatible Change.