The HTTP 406 status code stands for "Not Acceptable". It is a client error response indicating that the server cannot provide a response that matches the Accept headers specified by the client.

When is HTTP 406 Used?

  • When the client requests a specific content type the server does not support.
  • When the client requests a specific language, character set, or encoding the server cannot provide.
  • When an API client uses restrictive Accept headers that the server cannot satisfy.

How Does It Work?

The client includes an Accept header in the request to specify the desired format (e.g., application/json, text/html). If the server cannot respond with an acceptable format, it returns HTTP 406.

Example Scenarios

  • Requesting XML from an API that only supports JSON.
  • Requesting a language the server does not support (e.g., Accept-Language: fr-CA when only en-US is available).
  • Requesting an unsupported encoding (e.g., gzip when the server only supports br).

Example

Client Request (Asking for Unsupported Media Type)

    
        GET /api/data HTTP/1.1
        Host: example.com
        Accept: application/xml

Server Response (406 Not Acceptable)

    
        HTTP/1.1 406 Not Acceptable
        Content-Type: application/json

        { "error": "The requested content type 'application/xml' is not supported. Available types: application/json" }

Common Accept Headers

  • Accept: Specifies the media type (e.g., application/json, text/html).
  • Accept-Language: Specifies the preferred language (e.g., en-US, fr-FR).
  • Accept-Encoding: Specifies the preferred encoding (e.g., gzip, br).

Best Practices for Handling HTTP 406

  • Provide clear error messages indicating the available content types.
  • Use content negotiation to serve a default format if possible.
  • Document supported media types in API documentation.

Summary

HTTP 406 means the server cannot produce a response matching the client's Accept headers. It often occurs in APIs with content negotiation when clients request unsupported media types, languages, or encodings.