406 Not Acceptable: what the Accept header has to do with it

A 406 means the server can't produce the format your request asked for. How content negotiation works, why a WAF can cause it, and how to fix it in common frameworks.

· 6 min read · By the Spot Downtime team

A 406 Not Acceptable response means the server understood the request but can't produce a response that matches what the client said it would accept. It comes from content negotiation: the client lists the formats, languages or encodings it can handle, and the server has none of them. In practice, 406 is also one of the errors a web application firewall throws when a request looks wrong, so the same status has two very different causes.

How content negotiation works

A client describes what it can handle in request headers. The server compares them with what it can produce and picks one.

  • Accept lists media types, such as application/json or text/html.
  • Accept-Language lists languages, such as en-US or de.
  • Accept-Encoding lists compression formats, such as gzip or br.
  • Accept-Charset lists character sets. Browsers no longer send it, but old clients and scripts still do.

Each entry can carry a quality value: Accept: application/json;q=0.9, text/csv;q=0.5 means "JSON preferred, CSV if you must". A q=0 means "not acceptable". When nothing the server can produce matches, a strict server answers 406. A well-behaved 406 also says what it does have, usually in the body.

Many servers don't negotiate strictly. The HTTP standard allows ignoring the header and sending the default format anyway, and most servers do, which is why 406 is rare for plain websites.

Reproduce it with curl

Send the request with different Accept headers and compare:

bash
# What does it say with no preference?
curl -i https://api.example.com/reports/42

# Ask for JSON explicitly
curl -i -H "Accept: application/json" https://api.example.com/reports/42

# Ask for something it probably can't produce
curl -i -H "Accept: application/xml" https://api.example.com/reports/42

If the third request returns 406 and the first two work, you have a genuine negotiation failure: the client asked for a format the endpoint doesn't offer. If the first request returns 406 too, or a request that works in a browser fails from your script, the cause is probably something other than the Accept header.

Cause 1: the client asks for a format the server doesn't have

This is the textbook case, and it's common in APIs. A few examples:

  • Django REST Framework answers 406 with "Could not satisfy the request Accept header" when the Accept header matches none of the configured renderers.
  • Spring MVC returns 406 when a @RequestMapping has produces = "application/json" and the client sends Accept: application/xml, or when no message converter can write the return type in the requested format.
  • Rails with respond_to returns 406 (ActionController::UnknownFormat) if the action has no block for the requested format and the request is not HTML.
  • Express's res.format() sends 406 if none of the handlers match and you haven't defined a default.

The fix is on either side:

  • Client: send an Accept header the endpoint supports, or Accept: */* if you don't care. HTTP libraries sometimes set odd defaults, so print the headers you actually send.
  • Server: if clients routinely send */* or no header and still get 406, you've made the negotiation stricter than needed. Fall back to your default format instead of failing.
js
// Express: always have a default, so unknown Accept values still get an answer
res.format({
  "application/json": () => res.json(report),
  "text/csv": () => res.type("csv").send(toCsv(report)),
  default: () => res.status(406).json({ error: "Supported: application/json, text/csv" }),
});

File extensions can override the header

Some frameworks pick the format from the URL: /reports/42.json or ?format=csv. If the extension asks for a format the server doesn't render, you get 406 no matter what the Accept header says. Check the URL before the headers.

Cause 2: a firewall rule blocks the request

The more confusing source of 406 is not content negotiation at all. Apache's ModSecurity, with some rule sets, answers 406 for requests that trip a rule: a missing or empty User-Agent, a missing Accept header, an unusual User-Agent such as curl or python-requests, or a request body that looks like an attack. Some shared hosts enable this by default.

The signs that it's a WAF and not negotiation:

  • The response body is a generic error page from the host, not from your application.
  • The same URL works in a browser but fails from curl or a script.
  • Adding a browser-like User-Agent or an Accept header makes it work.
  • The error appears only on POST or PUT requests with certain content, such as HTML or SQL-like strings in a form field.
bash
# Does adding browser-like headers change the answer?
curl -i https://example.com/contact-form
curl -i -A "Mozilla/5.0" -H "Accept: text/html" https://example.com/contact-form

If that changes the result, look in the web server's error log for the rule ID (in ModSecurity logs it's a number in the id field). You can then ask your host to disable that one rule for the path, or whitelist it yourself if you control the server. Don't switch the whole firewall off to fix one rule.

Monitoring checks can trigger this too

An uptime check that gets 406 while browsers get 200 usually means a firewall is treating the monitor as a bot. Allow the monitor's requests (by user agent or IP) rather than weakening the rule for everyone.

Cause 3: compression and encoding

Rarely, an Accept-Encoding value the server can't honour produces 406 instead of an uncompressed response. Strict servers do this when the header excludes identity (for example Accept-Encoding: gzip;q=1, identity;q=0) and the content can't be compressed. The fix is to send a normal value such as gzip, deflate, br, or to remove a hand-written header from your client.

406 versus 415 and 400

People mix these up because they all involve content types. The direction decides which one you get:

  • 406 is about the response: the server can't produce what the client asked to receive (Accept headers).
  • 415 is about the request: the server won't read the body format the client sent (Content-Type). See 415 Unsupported Media Type.
  • 400 is for a request that is malformed in some other way. See 400 Bad Request.

Checking what a URL sends back

When a response looks wrong, look at the raw headers, including Content-Type and Vary: Accept on negotiated endpoints. The Vary header matters for caches: without it, a CDN can serve a cached JSON response to a client that asked for HTML.

HTTP headers checkerSee the status code and every response header a URL returns, from outside your network.

Catching it before users do

A 406 on an API usually means a client was updated, or a server change dropped a format. Neither shows up as an outage in your logs. An API monitor that sends the same Accept header your real clients use, and expects a specific status code and a JSON field in the body, will catch the regression. Spot Downtime treats any status other than the one you expect as down, and it confirms failures from three regions before alerting, so a single odd response doesn't page you.

Get new guides by email

Practical posts on monitoring, outages, error fixes and on-call, when they're published. No spam.

Unsubscribe from any email with one click. See our privacy policy.

Keep reading