406 Not Acceptable: Content Negotiation Mismatch
Accept headers (e.g., Accept, Accept-Language, Accept-Encoding). The server can serve the resource but only in formats that the client does not accept. This is a content negotiation issue — the client must either broaden its Accept headers or the server must support additional formats.
How Content Negotiation Works
The client sends headers that tell the server what responses it can handle:
- Accept – media types (e.g.,
application/json,text/html). - Accept-Language – languages (e.g.,
en-US,fr). - Accept-Encoding – compression methods (e.g.,
gzip,br). - Accept-Charset – character sets (e.g.,
utf-8).
The server evaluates these headers and chooses the best response format. If it cannot satisfy any of them, it returns 406.
Common Causes of 406 Errors
| Cause | Example | How to Fix |
|---|---|---|
| Client only accepts one format, server doesn't support it | Client sends Accept: application/xml but server only serves JSON. | Change client's Accept header to a supported format, or server adds XML support. |
| Language mismatch | Client sends Accept-Language: fr but server only has English content. | Add translations or fallback to a default language. |
| Encoding not supported | Client sends Accept-Encoding: br (Brotli) but server only supports gzip. | Client should accept gzip as fallback, or server should add Brotli support. |
| Strict Accept headers | Client uses Accept: application/json;q=1.0 with no wildcard. | Add Accept: */* or a broader range. |
| Server misconfiguration | Server doesn't properly handle Accept headers. | Check server configuration (e.g., Apache's mod_negotiation, Nginx's try_files). |
Example: 406 Response
A client requests JSON but the server only serves HTML:
406 vs. 415 Unsupported Media Type
| Status | Meaning | Direction |
|---|---|---|
| 406 Not Acceptable | Client's Accept headers don't match server's response formats. | Client asks for something server can't deliver (response side). |
| 415 Unsupported Media Type | Server doesn't support the media type of the request body. | Server can't process what client sent (request side). |
How to Fix 406 Errors
- If you're a client developer: Check your
Acceptheaders. Make sure they include the formats your application actually supports. Use wildcards likeAccept: */*orAccept: application/json, text/plain, */*to be more flexible. - If you're a server developer: Implement content negotiation properly. Support multiple formats (JSON, XML, HTML) and languages. Use quality values (
q) to prioritize client preferences. - If you're an end‑user: You'll likely see a 406 only when using an API client or a misconfigured website. Contact the site administrator or check your client settings.
Frequently Asked Questions
Is 406 a server error?
No, it's a client error (4xx). The client's Accept headers are too restrictive. However, the server can help by providing a list of supported formats in the response body or by falling back to a default format.
Can I ignore Accept headers and always return a default format?
Yes, many APIs do this to avoid 406 errors. They simply return JSON regardless of the Accept header (or fallback to HTML for browsers). This is common and acceptable in practice.
What is content negotiation used for?
It allows servers to serve the same resource in different formats, languages, or encodings based on client preferences. This is essential for internationalization, API versioning, and optimizing for different devices.