Content-Encoding versus Transfer-Encoding: representation codings and message framing

What it is

Content-Encoding lists the codings (gzip, br, zstd, deflate) applied to a representation beyond what its media type implies; RFC 9110 describes it as allowing data to be compressed without losing the identity of its underlying media type. The representation is the coded form: Content-Length, ETag and byte ranges all refer to the encoded bytes, the codings are listed in the order applied, and the client negotiates them with Accept-Encoding. Decoding normally happens only at the final recipient.

Transfer-Encoding (RFC 9112) lists transfer codings applied to form the HTTP/1.1 message body, primarily chunked, which frames content whose length is unknown when the headers are sent. RFC 9112 calls it a property of the message, not of the representation: any hop may add or remove codings. chunked must be the last coding and must not be applied twice; it is forbidden in 1xx and 204 responses. When both Transfer-Encoding and Content-Length are present, Transfer-Encoding wins, and RFC 9112 says such a message may indicate request smuggling and ought to be treated as an error.

In HTTP/2 (RFC 9113) and HTTP/3, framing is done by the protocol; Transfer-Encoding is a connection-specific field that must not appear, and only TE: trailers is allowed.

Why it matters

Mixing the two produces concrete faults: a proxy that compresses on the fly with Content-Encoding but keeps the origin's strong ETag breaks If-Range and conditional requests; a range request against a dynamically compressed response has no stable offsets; a hand-set Content-Length next to chunked framing is a smuggling vector; an HTTP/2 client that emits Transfer-Encoding: chunked is rejected as malformed.

How to apply

• Compress at one layer with Content-Encoding, make the ETag differ per encoding (or use weak validators), and send Vary: Accept-Encoding.
• Serve pre-compressed files as their own representation with a correct Content-Length; they can be cached and ranged.
• Let the server frame streaming HTTP/1.1 responses with chunked; do not compute Content-Length by hand for generated bodies.
• In proxies, never forward both fields; RFC 9112 requires removing Content-Length and processing the transfer coding.
• Remember that HEAD and 304 responses may carry Transfer-Encoding without a body.

Pitfalls

Content-Encoding: gzip on a .tar.gz download can make a browser decompress it and save a plain tarball under the .gz name; RFC 9110 mentions that user agents behave differently depending on whether a coding sits in Content-Type or Content-Encoding. Per RFC 9112, chunked is the only transfer coding a server may apply unless the client listed others in TE. A server must not send Transfer-Encoding at all unless the request was HTTP/1.1 or later.