4xx Client errors
Last updated Jul 26, 2023

406 - Not Acceptable

Benjamin Bouchet
Get your free
API
key now
4.8 from 1,863 votes
See why the best developers build on Abstract
START FOR FREE
Thank you! Your submission has been received!
Oops! Something went wrong while submitting the form.
No credit card required

The HTTP Status Code 405 means that the requested resource can only generate content that is deemed unaccepted by the Accept headers sent in the original request.

What is HTTP Status Code 406?


When developing or maintaining a web application, understanding HTTP status codes is crucial. These codes provide valuable information about the interactions between a client, such as a web browser, and a web server. They can help us debug issues, enhance user experience, and optimize traffic routing. In this post, we'll be focusing on one specific HTTP response status code, the HTTP Status Code 406.


The Basics of HTTP Status Code 406


HTTP Status Code 406, also known as "Not Acceptable", is part of the HTTP response status codes that indicate client error responses. Specifically, it's used when the requested resource, such as a web page, is not available in a format that would be acceptable to the client, based on the Accept headers sent in the HTTP request.


The Role of Accept Headers and Content Negotiation


The Accept headers play a significant role in the HTTP Status Code 406. These headers, sent by the client (e.g., a web browser), specify the MIME types that the client can understand and prefer. This is a part of proactive content negotiation, a mechanism where the client and the server negotiate over the best representation of a resource to deliver to the user.


When the server cannot provide a response that matches the criteria outlined in the Accept headers, it may return an HTTP response with status code 406. This response status code indicates that the server cannot generate a response matching the list of acceptable responses defined by the client.


Error Message and Client Error Responses


Usually, a 406 HTTP response status comes with an error message specifying the reason for the rejection. The server generates this error message to help the client understand why the requested resource cannot be served in an acceptable format. This falls under the category of client error responses, where the error is a result of the request made by the client, not a fault of the server.



When and How is HTTP Status Code 406 Used?


Usage in Web Development


In web development, HTTP status codes like 406 play an important role in crafting a user-friendly experience. For instance, if you're managing a WordPress site or any other content management system (CMS), you may encounter a situation where you need to serve different versions of a resource (HTML, XML, JSON, etc.) based on the user agent or the Accept headers sent by the client.


Implementation Across Different Programming Languages


HTTP Status Code 406 is represented differently across various programming languages and frameworks. For instance, the Rails HTTP status symbol for 406 is `:not_acceptable`. Similarly, in Symfony, it's represented by the HTTP status constant `Response::HTTP_NOT_ACCEPTABLE`, and in Python 2, it's the HTTP status constant `httplib.NOT_ACCEPTABLE`.


Handling the 406 Status Code


When a client receives a 406 HTTP response code, the appropriate reaction is to reattempt the request with different Accept headers. This is typically handled automatically by modern web browsers. However, sometimes manual intervention may be needed, particularly in the context of an API or a web application where custom Accept headers might be used.


For example, if you're running an Apache web server and you've encountered a 406 error, one solution might be to disable mod_security, a module that can block certain types of requests based on server-defined rules. However, this should be done cautiously as it can potentially expose the server to security risks.


The Challenge of Unsupported Media Type


In some cases, an HTTP response with a 406 status code could be due to an unsupported media type. For instance, if your web application serves resources in JSON format, but the client specifies `text/html` in the Accept header, the server may return a 406 status code, indicating that it can't serve the requested resource in the format desired by the client. This is where the importance of content negotiation comes into play, as it allows the client and server to agree on the most appropriate content representation.


Troubleshooting the 406 Status Code


Troubleshooting a 406 status code requires an understanding of the client-server interaction and the Accept headers. The first step in resolving the issue is to inspect the Accept headers sent in the HTTP request. Web browsers and other HTTP clients allow users to view and modify these headers, enabling a better understanding of why the server sent a 406 response.


Upon encountering a 406 status code, you might need to adjust the Accept headers or alter the server's available representations of the requested resource. In certain cases, you might need to configure your Apache web server or disable mod_security to allow for a broader range of acceptable status codes.


Beyond the Error Code


While HTTP Status Code 406 is considered a client error, it's worth noting that the resolution often involves changes on both the client and the server side. Whether it's adjusting the Accept headers in the client's HTTP request or modifying the server's content negotiation process, understanding this status code can lead to more efficient and effective web development practices.


Remember, each HTTP response status code, including 406, is a communication tool. It's not merely an error code, but a message from the web server, providing valuable feedback that can help improve your web application. So next time you encounter a 406 or any other status code, see it as an opportunity for optimization and improvement.



Example usage of HTTP Status Code 406


A Simpler Perspective


Imagine you're visiting a restaurant where you don't speak the language. You look at the menu and can't understand anything. You try to order a pizza, but the waiter looks puzzled and says, "Sorry, we don't serve pizza here." This is what happens when a client requests data from a server in a format that the server can't provide, resulting in an HTTP 406 status code.


A More Technical Look


When a client sends a request to the server, it can specify the format it prefers for the response data, such as JSON, XML, or HTML. This is done through the 'Accept' header in the HTTP request. If the server can't provide data in any of the requested formats, it returns a 406 status code, meaning "Not Acceptable."


Here's a concrete example. Let's say a client sends a GET request to the `/news` endpoint of a website and specifies `Accept-Language: fr` in the header, asking for the news in French. But the server only has English and German versions of the news. So, it responds with a 406 status code, indicating that it can't fulfill the request:



GET /news HTTP/1.1
Host: www.example.ai
Accept-Language: fr

HTTP/1.1 406 Method Not Acceptable
Content-Type: text/html
Content-Length: 242

<html>
  <head>
    <title>French Language Not Available</title>
  </head>
  <body>
   <p>Please choose a supported language:</p>
    <p><a href="/news/news-de.html">German</a></p>
    <p><a href="/news/news-en.html">English</a></p>
   </body>
</html>


Notice that the server does not simply refuse the request. It provides additional information about the available languages, helping the client to make an acceptable request next time.



What is the history of HTTP Status Code 406?


HTTP 406 is part of the HTTP/1.1 standard, which was first published in 1997. The code is used to indicate that the requested resource is capable of generating only content not acceptable according to the Accept headers sent in the request. This status code is part of the HTTP specification to enable content negotiation between the client and the server.



How does HTTP Status Code 406 relate to other status codes?


HTTP status codes are divided into five classes, with the first digit of the code indicating the class. The 4xx class, where 406 belongs, is for client errors, indicating the client has made a request that the server cannot or will not fulfill.


However, HTTP 406 is distinct from other 4xx status codes in its usage. For example, the 404 status code, also a client error, is returned when the server cannot find the requested resource. On the other hand, with 406, the server has found the resource, but it can't deliver it in the format specified by the client's Accept headers.


While using status codes, it's crucial to choose the correct one to ensure the client receives an appropriate response. For instance, in a scenario where a user attempts to confirm the creation of a new account with an invalid token, a 406 code would not be suitable. In such a case, a more appropriate status code might be 400 ("Bad Request") or 403 ("Forbidden").



Other Points of Interest: Handling HTTP 406 Status Code Errors


Apache Server


In an Apache server environment, you can handle HTTP 406 status code errors using the `.htaccess` file and the `mod_rewrite` module. For instance, you can set up a rule that matches all incoming requests to a certain URL that do not contain a specific `Accept` request header. If such a request is made, the server will return a 406 status code:



RewriteEngine on

RewriteCond %{REQUEST_URI} ^/users/json/?.*$
RewriteCond %{HTTP_ACCEPT} !application/json
RewriteRule ^(.*)$ https://airbrake.io/users/json$1 [R=406,L]

In this example, all requests to `https://airbrake.io/users/json` that do not contain an `Accept: application/JSON` request header will be met with a 406 response. The `R=406` flag at the end of the `RewriteRule` explicitly states that the response code should be 406.


Nginx Server


In an Nginx server environment, you can handle HTTP 406 status code errors using the `nginx.conf` configuration file. Here is an example of how you can configure a virtual server to return a 406 response code if a request does not include the appropriate `Accept` request header:



server {
    listen 80;
    listen 443 ssl;
    server_name airbrake.io;
    location /users/json {
        if ($http_accept != application/json) {
            return 406 https://airbrake.io/users/json$request_uri;
        }
    }
}

In this example, similar to the Apache server example above, a request to `https://airbrake.io/users/json` that doesn't include an `Accept: application/JSON` request header will be met with a 406 response code.



Handling HTTP 406 Errors in Applications


Various programming languages and frameworks provide support for handling HTTP status codes, including 406. Here are some examples:


- .NET: `HttpStatusCode.NotAcceptable`

- Rust: `http::StatusCode::NOT_ACCEPTABLE`

- Rails: `:not_acceptable`

- Go: `http.StatusNotAcceptable`

- Symfony: `Response::HTTP_NOT_ACCEPTABLE`

- Python3.5+: `http.HTTPStatus.NOT_ACCEPTABLE`

- Java: `java.net.HttpURLConnection.HTTP_NOT_ACCEPTABLE`

- Apache HttpComponents Core: `org.apache.hc.core5.http.HttpStatus.SC_NOT_ACCEPTABLE`

- Angular: `@angular/common/http/HttpStatusCode.NotAcceptable`


Each of these refers to the HTTP 406 status code and can be used to handle such errors in your application, enabling you to provide meaningful feedback to your users or take other appropriate actions when such a situation arises.

Get your free
API
key now
4.8 from 1,863 votes
See why the best developers build on Abstract
Thank you! Your submission has been received!
Oops! Something went wrong while submitting the form.
No credit card required