HTTP 415 Unsupported Media Type: o que significa e como corrigir

O que este erro significa e como reconhecê-lo

• Um cliente de API, formulário do navegador, ferramenta de upload, verificação de monitoramento ou aplicação informa 415 Unsupported Media Type.
• A resposta pode afetar um endpoint, método HTTP ou formato de solicitação específico, enquanto outras páginas e rotas continuam funcionando.
• Uma solicitação pode falhar após a alteração do formato do corpo, do Content-Type, da codificação do conteúdo, do tipo de upload ou da biblioteca cliente.
• Os cabeçalhos da resposta podem revelar o servidor, proxy ou CDN que gerou a resposta, além de informações sobre cache, autenticação, redirecionamento ou limite de requisições.
• A resolução de DNS e a negociação de TLS podem ser bem-sucedidas porque uma resposta HTTP foi recebida; essas verificações não comprovam que o conteúdo da solicitação foi aceito.

Causas principais, por probabilidade

1. Tipo de mídia da solicitação não compatível: O endpoint não aceita o valor enviado em Content-Type, como ao enviar dados de formulário para uma rota que aceita apenas JSON.
2. Cabeçalho da solicitação incorreto ou ausente: O cliente omite o Content-Type, envia um valor digitado incorretamente ou identifica o corpo como um formato diferente do real.
3. Codificação do conteúdo não compatível: A solicitação usa uma codificação de compressão ou transferência que o componente receptor não consegue processar.
4. Endpoint ou método incorreto: A solicitação é enviada para uma rota que espera outra representação, formato de upload ou método HTTP.
5. Validação por proxy, CDN, WAF ou servidor web: Um intermediário rejeita a solicitação antes que ela chegue à aplicação ou aplica regras diferentes dos requisitos documentados pela aplicação.
6. Alteração recente na aplicação ou configuração: Uma implantação, mudança de roteamento, atualização do parser, integração de autenticação ou regra de proxy altera os formatos de solicitação aceitos.

O código de status, por si só, não identifica o componente responsável. Confirme os detalhes da solicitação e os logs correspondentes antes de considerar autenticação, permissões, limites ou configuração upstream como a causa.

Como corrigir

Para visitantes e usuários não técnicos

1. Repita a ação exata uma vez. Confirme a URL e, se aplicável, a ação de upload ou formulário selecionada. Evite enviar repetidamente a mesma solicitação.
2. Use o fluxo normal de login. Se o endpoint exigir uma conta, faça login pela interface padrão do site em vez de alterar manualmente os cabeçalhos ou cookies da solicitação.
3. Verifique o arquivo ou conteúdo enviado. Se o erro ocorrer durante um upload ou envio de formulário, use o formato solicitado pelo site e evite apenas renomear um arquivo sem convertê-lo.
4. Tente a interface compatível com o site. Se uma ferramenta de API, extensão do navegador ou integração personalizada falhar, compare-a com o formulário web ou a aplicação normal do site.
5. Entre em contato com o proprietário do site se o problema persistir. Inclua a URL ou recurso afetado, o horário aproximado, o resultado HTTP 415 e a ação que falhou. Não envie senhas, cookies, tokens de autorização nem o conteúdo de arquivos privados.

Para desenvolvedores e clientes de API

1. Registre a estrutura completa da solicitação. Anote o método, o caminho da URL, os parâmetros de consulta, o Content-Type, a codificação do conteúdo, o valor relevante de Accept e uma descrição sanitizada do corpo. Não registre segredos ou dados pessoais sem necessidade.
2. Compare a solicitação com o contrato do endpoint. Verifique se a rota e o método aceitam a representação enviada. Por exemplo, confirme se o endpoint espera JSON, dados codificados como formulário, dados de formulário multipart, XML ou um formato de upload específico.
3. Faça a declaração corresponder ao corpo. Não identifique dados de formulário como JSON nem envie um corpo comprimido sem a codificação correspondente compatível. Deixe a biblioteca cliente criar os limites multipart quando ela oferecer esse recurso.
4. Use uma reprodução mínima. Remova campos opcionais e middleware não relacionado sempre que possível e repita a mesma solicitação com um corpo conhecido como compatível. Preserve a solicitação original para comparação.
5. Inspecione a resposta. Verifique o status, o Content-Type, os indicadores de cache, os identificadores do servidor ou proxy, os redirecionamentos e qualquer corpo de erro. Uma resposta gerada por um gateway pode não refletir a validação feita pela própria aplicação.
6. Verifique os logs na camada responsável. Compare o horário da solicitação, a rota e o identificador de correlação ou solicitação com os logs da aplicação, do servidor web, do proxy reverso, da CDN ou do WAF.
7. Aplique a correção mais específica possível. Corrija o cabeçalho do cliente, o serializer, o formato de upload, o contrato da rota ou a regra intermediária com escopo restrito. Não desative amplamente a validação, a autenticação ou a filtragem de segurança como primeira medida.
8. Teste novamente e verifique o comportamento adjacente. Repita a solicitação original, depois teste o mesmo endpoint com os formatos compatíveis e confirme que as rotas relacionadas continuam retornando os códigos de status esperados.

Para proprietários e operadores de sites

1. Reproduza a falha usando o mesmo tipo de cliente e método de solicitação, registrando cabeçalhos sanitizados e o tempo da operação.
2. Determine se o 415 foi gerado pela aplicação, pelo servidor web, pelo proxy reverso, pela CDN ou pelo WAF comparando os cabeçalhos da resposta e os logs de cada camada.
3. Revise implantações recentes e alterações no roteamento, no processamento de solicitações, no tratamento de uploads, no encaminhamento do proxy, na codificação do conteúdo e nas regras de segurança.
4. Confirme que caches ou intermediários não estão servindo uma resposta armazenada inadequada para a solicitação.
5. Corrija a rota ou o contrato específico do cliente, documente os formatos aceitos e mantenha logs suficientes para confirmar a correção.
6. Se a solicitação não for compatível intencionalmente, certifique-se de que o comportamento do endpoint e a documentação voltada ao cliente deixem claro qual formato é aceito.

Prevenção e como verificar a correção

• Documente os métodos HTTP, tipos de mídia, codificações e formatos de upload aceitos por cada endpoint importante.
• Use testes automatizados para tipos representativos de solicitações JSON, formulário, multipart e outros formatos compatíveis após alterações na aplicação ou no proxy.
• Mantenha as configurações de roteamento, processamento de solicitações, proxy, CDN e WAF sob controle de versão, com alterações passíveis de revisão.
• Monitore os códigos de status por rota e método, em vez de tratar todas as respostas 4xx como uma única categoria.
• Mantenha IDs de correlação e logs devidamente sanitizados da aplicação e dos intermediários disponíveis durante o período de retenção relevante.
• Faça as integrações de clientes falharem de forma clara quando os tipos de mídia aceitos pelo servidor mudarem e teste-as de acordo com o contrato documentado.

Perguntas frequentes