406 Not Acceptable
The server cannot produce a response matching the list of acceptable values.
Usually happens because:
- ☑ Client requests application/xml format but
- ☑ Mismatch in Accept-Language headers between
🔍 Quick Checklist:
Meaning
The HTTP 406 Not Acceptable client error 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 (e.g. Accept, Accept-Language, Accept-Encoding).
Root Causes
- Client requests application/xml format but API only supports application/json.
- Mismatch in Accept-Language headers between browser preferences and server translations.
| Cause | Frequency |
|---|---|
| Client requests application/xml format but | ⭐⭐⭐⭐⭐ |
| Mismatch in Accept-Language headers between | ⭐⭐⭐⭐ |
Common Mistakes
- Hardcoding JSON returns in application controllers without checking request Accept header flags.
- Misconfiguring translation packages, triggering 406 for valid languages.
How to Fix
Framework-Specific Examples
Using req.accepts() to check format matching in Express.
app.get('/api/users', (req, res) => {
if (!req.accepts('json')) {
return res.status(406).send('Not Acceptable: JSON only');
}
});Server Configuration Examples
Rejecting request format configurations.
# Nginx passes formats downstream to appPrevention
- Use default format fallbacks (e.g. default to JSON) instead of returning 406 for format mismatches unless strictly required.
- Verify API clients send correct Accept headers.
Frequently Asked Questions (FAQ)
Q: What is content negotiation?
Content negotiation is the mechanism defined in HTTP specs that allows a client and server to agree on the best representation format (e.g., JSON vs XML, or English vs Spanish) for a resource.
Q: Why is 406 rarely returned by APIs?
Most APIs ignore the client's 'Accept' header and simply return application/json by default, avoiding the overhead of 406 error checks.
Q: Can I return a list of supported formats in a 406 response?
Yes, it is highly recommended to include a list of supported mime-types in the response body to guide clients.
Q: Which headers trigger 406 Not Acceptable?
The main headers are 'Accept', 'Accept-Charset', 'Accept-Encoding', and 'Accept-Language'.