406 Not acceptable

What the 406 Not Acceptable error means

When a client makes an HTTP request, it can include Accept, Accept-Language, Accept-Encoding, and other headers to tell the server what formats it can handle. Examples:

• Accept: text/html
• Accept: application/json
• Accept-Language: en-US
• Accept-Encoding: gzip, deflate

406 occurs during content negotiation. The server checks the request headers and tries to respond with a representation that matches the client’s preferences. If there is no available resource representation that satisfies those preferences, the server returns 406 Not Acceptable.

Key takeaway about how it differs from other 4xx errors:

• 404 Not Found means the resource doesn’t exist.
• 403 Forbidden means you’re not allowed to access it.
• 406 Not Acceptable means the resource exists, but none of its representations satisfy the client’s Accept criteria.

Common causes of 406 Not Acceptable

Client-side causes

• Overly strict Accept headers: The client requests a format the server doesn’t offer for that resource.
• Incorrect interpretation of content types: The client believes a resource is available in a given format when it’s not.
• Aggressive caching: A cached response with an old Content-Type prevents a valid representation from being served.
• Misconfigured user agents or proxies: A proxy may modify Accept headers or strip content types, leading to mismatches.

Server-side causes

• Content negotiation misconfiguration: The server’s Vary and negotiation rules don’t align with available representations.
• Missing or misdeclared content types: The resource is served with an incorrect Content-Type header that doesn’t match accepted formats.
• Dynamic endpoints with limited formats: An API endpoint only supports JSON, but the client asks for XML, or vice versa.
• Proxies or gateways altering responses: Front-end proxies may convert content or fail to honor negotiable formats.

Real-world patterns

• API endpoints that only support application/json but are asked for application/xml.
• Static sites where a page exists as HTML but a script forces an Accept header for a non-existent format.
• A CDN or edge server that normalizes responses but doesn’t provide a fallback for certain formats.

How to diagnose a 406 Not Acceptable

• Check the request headers: Inspect Accept, Accept-Language, and Accept-Encoding to see what the client is requesting.
• Review server logs: Look for negotiation-related messages around the request, including Vary headers.
• Verify available representations: Confirm which formats the resource can actually serve (e.g., HTML, JSON, XML, YAML).
• Inspect Content-Type of responses: Ensure the server is returning a Content-Type that matches a format you advertise as available.
• Test with simple requests: Use curl or a tool like Postman to request different formats explicitly, e.g.:
• curl -H "Accept: text/html" https://example.com/resource
• curl -H "Accept: application/json" https://example.com/resource
• Check caching: Clear relevant caches and bypass proxies to determine if a cached 406 is causing the issue.
• Consider proxies and CDNs: Some intermediaries implement their own content negotiation. Verify their configuration.

Practical fixes for developers and operators

If you control the server or API

• Align Accept and available representations:
• Ensure the server only negotiates on formats you actually support.
• If a requested format isn’t available, consider returning a 406 with a helpful message or a 415 Unsupported Media Type if the issue is the payload not the format.
• Implement sensible defaults:
• Serve text/html for browsers and application/json for API clients when possible, with content negotiation fallback.
• Correct Content-Type headers:
• Always set Content-Type to a value that matches the response body, e.g., application/json for JSON responses, text/html for HTML.
• Review Vary headers:
• Use Vary: Accept (and possibly Accept-Encoding) to inform caches about negotiation-based variations.
• Provide explicit fallbacks:
• If Accept: / is present and no specific format is negotiable, return a default representation rather than 406.
• Test edge cases:
• Simulate requests with unusual or narrow Accept headers to confirm behavior.

If you’re a site operator using a CMS or framework

• Check how the framework handles content negotiation:
• Some frameworks have built-in negotiators that may need configuration or extension for your use case.
• Review plugins and middleware:
• Some add or modify Accept handling. Ensure compatibility with your content types.
• Clear and refresh CDN rules:
• Ensure edge caches aren’t serving stale variants that cause 406s.

If you’re a client debugging a 406

• Relax the Accept header temporarily:
• Try Accept: / or Accept: text/html to see if a broader representation resolves the issue.
• Explicitly request a known format:
• If you know the server supports JSON, try Accept: application/json and see if the response improves.
• Check proxy or VPN influence:
• Disable proxies or VPNs to determine if the issue lies with an intermediary altering headers.
• Review API versioning:
• Some APIs require a version specifier in the path or header. Ensure you’re asking for a version that supports the format you want.

A quick comparison: 406 Not Acceptable vs other content-negotiation errors

Best practices to prevent 406 in production

• Publish a clear content negotiation policy:
• Document which formats are supported for each resource or endpoint.
• Use well-defined content types:
• Align Accept header values with actual Content-Type headers of responses.
• Implement robust error messages:
• When returning 406, include guidance on acceptable formats and how to request them.
• Avoid over-strict negotiation:
• Where possible, fallback to a reasonable default if the client’s preferences can’t be fully satisfied.
• Test with real clients:
• Validate behavior with common browsers, API clients, and proxies used by your audience.

When 406 Not Acceptable is not the right fix

In some cases, 406 is not ideal. Alternatives include:

• 200 OK with a default representation, plus a note about preferred formats.
• 415 Unsupported Media Type if the problem is the request payload format rather than the response format.
• 400 Bad Request if the problem stems from a malformed Accept header or other request syntax issues.

If you’re deploying an API or website, prefer informative 406 responses that guide the client to a valid path, and avoid ambiguous or empty responses that leave clients guessing. Sslvpn.poscoenc.com: Understanding SSL VPN basics and the best VPN alternative

Final recommendations

• For developers: audit your endpoints for negotiate-ability. Ensure you only offer formats you can reliably return and document them clearly. Implement helpful error messages when a 406 is unavoidable.
• For operators: investigate intermediaries (CDNs, proxies) that could alter headers or caches, and align edge behavior with your origin’s content negotiation rules.
• For clients: start with broad Accept headers, then narrow down to test specific formats. Clear caches and bypass proxies during diagnosis.

By understanding the intent behind 406 Not Acceptable and applying targeted checks, both on the client side and server side, you can reduce or eliminate these errors, delivering a smoother, more predictable experience for users and integrations alike.