406 Not Acceptable: o que significa e como corrigir

O que significa 406 Not Acceptable

O HTTP suporta negociação de conteúdo por meio de uma família de cabeçalhos Accept: Accept para o tipo de mídia da resposta, Accept-Language para o idioma, e Accept-Encoding para a compressão. Um cliente pode enviar qualquer um desses para dizer "só me dê uma resposta que eu consiga usar". Pela RFC 9110, se o servidor não consegue produzir uma representação que o cliente indicou que aceitaria, e opta por sinalizar isso em vez de enviar algo mesmo assim, ele responde 406. Na prática, a maioria dos servidores ignora um cabeçalho Accept restrito e envia a resposta padrão de qualquer jeito, o que é o motivo de um 406 genuíno ser menos comum do que o próprio cabeçalho.

Como o erro aparece

Um navegador raramente dispara um 406 em carregamentos normais de página, porque navegadores enviam cabeçalhos Accept permissivos que combinam com quase tudo que um servidor oferece. Ele aparece bem mais em clientes de API, scripts e ferramentas de linha de comando que definem um cabeçalho Accept restrito:

curl -i -H "Accept: application/xml" https://api.example.com/v1/status
HTTP/1.1 406 Not Acceptable
Content-Type: application/json

Nesse exemplo o cliente pediu só XML e a API só consegue produzir JSON, então o servidor recusa em vez de enviar um formato que o cliente explicitamente disse que não queria.

O que causa um 406 Not Acceptable

• Negociação de conteúdo genuinamente falhando. Um cabeçalho Accept, Accept-Language ou Accept-Encoding nomeando só formatos que o servidor não consegue produzir, mais frequentemente um cliente pedindo XML de uma API só-JSON, ou uma variante de idioma específica que o servidor não tem.
• Um firewall de aplicação web em hospedagem compartilhada. Essa é uma causa muito comum no mundo real que não tem nada a ver com negociação de conteúdo: regras de ModSecurity e WAFs parecidos em ambientes de hospedagem compartilhada bloqueiam requisições cujo cabeçalho Accept parece incomum, ausente ou automatizado, e respondem 406 como a resposta de bloqueio independentemente do que estava sendo negociado de fato.
• Uma API que só serve JSON, atingida por um cliente enviando Accept: text/html. Algumas APIs são rígidas quanto a isso e recusam em vez de degradar, o que aparece como 406 para qualquer cliente, incluindo uma aba de navegador aberta direto no endpoint.
• Uma regra de proxy reverso ou CDN mal configurada que inspeciona e rejeita com base no cabeçalho Accept por motivos de cache ou de filtragem de bots, sem relação com o que o servidor de origem realmente pode produzir.
• Tratamento excessivamente rígido de Accept-Encoding. Um servidor configurado para recusar qualquer requisição que não liste um método de compressão que ele prefere, em vez de recorrer a uma resposta não comprimida.

Como saber de quem é a culpa

Se um script ou uma integração específica é a única coisa recebendo 406, confira o que os cabeçalhos Accept dela dizem, já que um cabeçalho restrito ou mal configurado do lado do cliente costuma ser a causa direta. Se a mesma requisição funciona com um cabeçalho Accept simples e permissivo mas falha com um específico, o servidor genuinamente não consegue servir aquele formato. Se o tráfego normal do navegador também é afetado, ou o erro começou logo depois de uma mudança de hospedagem ou de WAF sem nenhuma mudança de código do seu lado, regras de segurança de hospedagem compartilhada são a causa mais provável, e rodar uma verificação HTTP a partir de várias localidades com os cabeçalhos exatos que a sua integração envia é a forma mais rápida de confirmar se o bloqueio é consistente ou específico de uma rede.

Como corrigir um 406 Not Acceptable

Se você é um visitante

1. Remova ou relaxe o cabeçalho Accept em qualquer script ou ferramenta que esteja fazendo a requisição, se você o controlar, e deixe que aceite o formato padrão que o servidor oferece.
2. Confira a documentação da API para saber quais tipos de conteúdo e idiomas ela suporta antes de assumir que o servidor está quebrado.
3. Tente a requisição a partir de um navegador diretamente, já que navegadores enviam cabeçalhos Accept amplos e raramente encontram esse erro, o que ajuda a confirmar que o bloqueio é específico dos cabeçalhos do seu cliente.

Se você administra o site

1. Confira as suas regras de ModSecurity ou WAF primeiro se o 406 for inesperado e generalizado, já que ambientes de hospedagem compartilhada frequentemente bloqueiam por padrões do cabeçalho Accept em vez de por uma falha genuína de negociação. Olhe os próprios logs do WAF em busca do id da regra que disparou antes de mexer no código da aplicação.
2. Confirme quais formatos a sua API realmente serve, e ou suporte mais do que clientes reais pedem ou documente a exigência com clareza para que um 406 seja informativo em vez de surpreendente.
3. Recorra a uma representação padrão em vez de recusar totalmente, onde isso for aceitável para a sua API, já que a maioria dos clientes do mundo real lida melhor com "aqui está JSON mesmo você tendo pedido de forma ampla" do que com uma rejeição direta.
4. Verifique regras de proxy reverso e CDN em busca de qualquer coisa inspecionando o cabeçalho Accept para cache ou gestão de bots, já que uma regra criada para um propósito pode produzir 406 como efeito colateral para tráfego não relacionado.

Como prevenir um 406 derrubando uma integração

Um 406 introduzido por uma atualização de segurança do provedor de hospedagem ou uma nova regra de WAF não vai parecer uma queda vista de dentro da sua própria rede, já que as suas próprias requisições podem usar cabeçalhos diferentes dos de uma integração afetada. Uma verificação HTTP agendada que envia o mesmo cabeçalho Accept que os seus clientes reais usam, com uma asserção no código de status esperado, pega uma falha de negociação no momento em que ela começa. Verificar a partir de várias localidades também ajuda a separar uma regra de WAF que afeta toda a hospedagem de uma que só se aplica em certos nós de borda.

Erros relacionados

Veja 403 Forbidden para o caso intimamente relacionado de uma regra de WAF ou de bot bloqueando uma requisição totalmente em vez de por negociação de conteúdo, a visão geral dos 4xx para a família mais ampla, e 413 Payload Too Large em outro ponto deste lote.

Perguntas frequentes

O 406 é o mesmo que um erro de CORS?

Não. Falhas de CORS acontecem porque o navegador se recusa a expor uma resposta cross-origin para o script que a chamou; o 406 é o próprio servidor recusando produzir um corpo de resposta porque não consegue satisfazer o formato, idioma ou codificação pedidos.

Por que só vejo 406 do curl ou do Postman, nunca do navegador?

Navegadores enviam cabeçalhos Accept amplos e permissivos por padrão. Ferramentas como o curl não enviam nada ou enviam um cabeçalho restrito a menos que você defina um explicitamente, o que é muito mais propenso a disparar uma falha genuína de negociação ou acionar uma regra de WAF ajustada para sinalizar cabeçalhos incomuns.

Um 406 pode vir do ModSecurity mesmo com meu cabeçalho Accept completamente normal?

Sim. Muitos conjuntos de regras de ModSecurity em hospedagem compartilhada sinalizam requisições como automatizadas com base em uma combinação de sinais, incluindo a estrutura e a ordem exatas dos cabeçalhos Accept, e respondem 406 como uma resposta de bloqueio genérica em vez de porque a negociação de conteúdo realmente falhou.

Minha API deveria devolver 406 ou simplesmente recorrer ao JSON?

Recorrer a um formato sensato é mais amigável para clientes do mundo real e é o que a maioria das APIs em produção faz. Devolver 406 é defensável quando servir o formato errado silenciosamente seria ativamente enganoso para quem chamou.

Qual é a diferença entre 406 e 415?

O 406 é sobre o que o cliente consegue aceitar na resposta. O 415 Unsupported Media Type é sobre o que o servidor consegue aceitar no corpo da requisição que o cliente enviou. Eles cobrem direções opostas da mesma ideia de negociação.