An HTTP 406 error occurs when a server cannot generate a response that matches the client's declared preferences in the request headers. This typically involves the Accept header, where the browser asks for content formats the server cannot or will not provide.
Understanding the causes and fixes for this status helps developers and site visitors resolve content negotiation issues quickly while maintaining a smooth user experience.
| Status Code | Category | Typical Cause for 406 | Quick Action |
|---|---|---|---|
| 406 Not Acceptable | Client Error | Server cannot match requested content types, languages, or charsets | Adjust Accept headers or server configuration |
| 400 Bad Request | Client Error | Malformed syntax in the request | Validate request format and parameters |
| 404 Not Found | Client Error | Requested resource does not exist | Check URL path and routing |
| 500 Internal Server Error | Server Error | Unexpected server-side condition | Review server logs and recent changes |
Understanding Content Negotiation in HTTP
Content negotiation allows clients and servers to agree on formats, languages, and encodings. When headers request unsupported combinations, the server responds with HTTP 406 to signal that acceptable representations cannot be produced.
Developers should map the Accept header against the actual endpoints and middleware layers to ensure declared capabilities align with server logic.
Common Triggers for HTTP 406 Errors
Misconfigured server rules or overly strict Accept headers often trigger 406 responses. This section outlines the most frequent scenarios developers and administrators encounter.
- URL patterns that do not match available handlers
- Wildcard or missing entries in Accept headers
- Static file serving without proper type negotiation
- Security modules or plugins blocking certain content types
- Caching layers serving mismatched representations
Server-Side Configuration Fixes
Adjusting server settings can resolve most 406 issues. Web platforms such as Apache, Nginx, and application frameworks rely on explicit rules that define which content types are negotiable.
Apache and Nginx Directives
Modifying configuration blocks to include broader MIME mappings or correcting path-based handlers can restore compatibility. Always verify syntax after changes and reload services gracefully.
Application Framework Settings
Frameworks like Django, Express, and Laravel expose content negotiation through route definitions and middleware. Reviewing these settings ensures that API and web endpoints honor the requested representations.
Client-Side Header Adjustments
Clients, including browsers and API tools, send Accept headers that may be too narrow. Broadening these headers or removing unsupported formats can prevent 406 responses when accessing public services.
Best Practices to Avoid Future 406 Errors
Implementing clear content negotiation strategies reduces errors and improves interoperability between services.
- Define supported media types in API documentation
- Use feature detection on the client before requesting content
- Standardize error payloads to include negotiation hints
- Monitor logs for recurring 406 patterns after deployments
- Validate configuration changes in staging before production
FAQ
Reader questions
Why does my API call return 406 even when the endpoint exists?
The request likely includes an Accept header for a format the API does not support, such as application/xml when the server only serves JSON.
Can browser extensions cause an HTTP 406 response?
Yes, extensions that modify request headers may inject unsupported Accept values, leading the server to reject the negotiation.
Is HTTP 406 related to authentication issues?
Not directly, because 401 and 403 handle authentication, while 406 focuses on content representation compatibility.
How can I test if my server properly handles Accept headers?
Use curl or API clients to send requests with different Accept headers and observe whether the server returns 200 or 406.