Accept-Encoding

The Accept-Encoding header specifies which response content codings are acceptable to the client.

This header is typically used to indicate the user agent supports compressed response messages, such as gzip.

Usage in requests

Writing requests (clients)

Write an Accept-Encoding header listing which content codings that the user-agent is capable of decoding, especially compression methods. Check the response Content-Encoding header to determine how to decode the message body, if necessary.

Reading requests (servers)

Using the Accept-Encoding header to select a response content coding is not trivial; keep a mapping of supported content-codings to available encoders or encoded representations, and use a library to match the incoming Accept-Encoding to an available encoding. If more than one representation could be selected from, add a Vary header of Vary: Accept-Encoding to indicate to caches that the response might vary based on this header.

For HTTP/Web applications, consider using a transforming HTTP gateway or cache to perform this step, instead of adding this complexity in the application.

Usage in responses

When used in a response, Accept-Encoding indicates that the client's selected content coding is not understood, and the client should re-make the request with one of the listed content codings.

Writing responses (servers)

The server should first ensure the resource exists, that the user-agent has the proper credentials to make the request, and any other checks that can be performed without needing to know the exact details of the request-body.

If the server receives a request from a client with a Content-Encoding value that it does not understand, send 415 Unsupported Media Type with an Accept-Encoding header listing the content codings the server can accept from clients.

Clients will see the presence of this header in a 415 Unsupported Media Type response as an indication that the Content-Encoding specifically was invalid. So, for reasons besides a Content-Encoding errors (e.g. an invalid Content-Type), do not supply this header.

Reading responses (clients)

Reading the Accept-Encoding header is only necessary from a response with 415 Unsupported Media Type. In this case, the client should re-make the request with one of the listed content codings listed in the response Accept-Encoding header.

Clients who would like to handle this error before writing the request body should send Expect: 100-continue. See the Content-Encoding header for information about how to make requests with a content encoding.

Overview table

Name: Accept-Encoding
Description: Specifies which response content codings are acceptable.
Direction: Both
Negotiates: Content-Encoding
List usage in: Vary
Specification: RFC 9110: HTTP Semantics §12.5.3. Accept-Encoding

Syntax

Accept-Encoding  = #( codings [ weight ] )
codings          = content-coding / "identity" / "*"
weight = OWS ";" OWS "q=" qvalue
qvalue = ( "0" [ "." 0*3DIGIT ] )
       / ( "1" [ "." 0*3("0") ] )

Examples

Indicate support for compress, gzip:

Accept-Encoding: compress, gzip

Implementations

Node.js

accepts
negotiator

History

1999-06: RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1 §14.3. Accept-Encoding. This version requires at least one item in the list.
2014-06: RFC 7231: HTTP/1.1 Semantics and Content §5.3.4. Accept-Encoding describes usage in requests, for listing responses that the client finds acceptable.
2015-11: RFC 7694: HTTP Client-Initiated Content-Encoding describes usage in responses, for the server to indicate which encodings the client may pick for encoding its request.
2022-06: Usage in both directions is combined into RFC 9110 §12.5.3. Accept-Encoding