406 Not Acceptable

Description

The 406 Not Acceptable status code indicates that the server cannot produce a response matching the list of acceptable values defined in the request's proactive content negotiation headers, and the server is unwilling to supply a default representation.

Content negotiation headers include: - Accept (for media types) - Accept-Language (for languages) - Accept-Encoding (for content encodings) - Accept-Charset (for character sets, though less common in modern applications)

This status code is returned when a client specifies strict requirements about the type of response it can accept, but the server cannot fulfill those requirements. Instead of providing a response in a format the client didn't explicitly accept, the server returns a 406 Not Acceptable status.

Syntax

The server responds with a 406 Not Acceptable status and typically includes information about available formats:

HTTP/1.1 406 Not Acceptable
Content-Type: application/json
Content-Length: [length in bytes]

{
  "error": "Not Acceptable",
  "message": "Cannot generate the requested format",
  "available_formats": [list of formats the server can provide]
}

Examples

Media Type Negotiation Example

A client requests data in a format the server doesn't support:

Client Request:

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

Server Response:

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

{
  "error": "Not Acceptable",
  "message": "Cannot provide resource in XML format",
  "available_formats": ["application/json", "text/html", "text/csv"]
}

Language Negotiation Example

A client requests content in a language the server doesn't support:

Client Request:

GET /documentation HTTP/1.1
Host: docs.example.org
Accept-Language: fr-FR, fr;q=0.9

Server Response:

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

{
  "error": "Not Acceptable",
  "message": "Documentation is not available in French",
  "available_languages": ["en-US", "es-ES", "de-DE", "ja-JP"],
  "translation_url": "https://translate.example.org/docs"
}

Multiple Content Negotiation Example

A client makes a request with multiple strict content negotiation requirements:

Client Request:

GET /api/report/sales HTTP/1.1
Host: api.example.com
Accept: application/pdf
Accept-Language: it-IT
Accept-Encoding: br

Server Response:

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

{
  "error": "Not Acceptable",
  "message": "Cannot satisfy the requested content negotiation parameters",
  "details": {
    "format": {
      "requested": "application/pdf",
      "available": ["application/json", "text/csv", "application/vnd.ms-excel"]
    },
    "language": {
      "requested": "it-IT",
      "available": ["en-US", "es-ES", "fr-FR"]
    }
  }
}

Summary

The 406 Not Acceptable status code plays an important role in content negotiation, allowing servers to clearly indicate when they cannot fulfill a client's specific format, language, or encoding requirements. Rather than providing content in a format the client hasn't explicitly accepted, servers use this status code to maintain transparency and allow clients to make informed decisions about how to proceed. In modern web applications, this status code is most commonly used for API format negotiation, though it can also apply to language preferences, character encodings, and other content characteristics.