HTTP 405 Method Not Allowed: o que significa e como corrigir

O que este erro significa e como reconhecê-lo

• Um navegador, cliente de API, ferramenta de monitoramento ou verificador recebe 405 Method Not Allowed.
• Um método HTTP falha enquanto outro método para a mesma rota pode funcionar.
• O problema pode afetar uma URL, um padrão de rota, um cliente ou uma implantação específicos, e não o site inteiro.
• A resposta pode incluir um cabeçalho Allow listando os métodos permitidos.
• Outros cabeçalhos podem revelar informações sobre redirecionamento, cache, autenticação, proxy, CDN ou servidor.
• Como uma resposta HTTP foi recebida, a resolução de DNS e a negociação de TLS podem já ter sido concluídas, mas isso não prova que a aplicação ou a rota estejam configuradas corretamente.

Causas principais, por probabilidade

Causas comuns

1. O método não é compatível com a rota. O endpoint pode aceitar GET, mas rejeitar POST, ou aceitar POST, mas rejeitar um método de atualização, como PUT ou PATCH.
2. Regras de roteamento ou do servidor web rejeitam o método. Uma rota, um virtual host ou uma política do servidor pode não encaminhar a requisição ao handler pretendido.
3. Um proxy reverso, CDN ou WAF retorna a resposta primeiro. Um intermediário pode aplicar restrições de método ou encaminhar a requisição de forma diferente da origem.
4. A requisição não corresponde ao contrato da aplicação. O caminho, a barra final, o tipo de conteúdo, o host, o estado de autenticação ou outros detalhes da requisição podem selecionar outra rota ou regra de validação.
5. Uma implantação ou alteração de configuração recente introduziu uma incompatibilidade. As rotas da aplicação, as regras do proxy, os métodos permitidos e o comportamento de cache podem não estar mais de acordo.
6. Uma política intencional ou o design do endpoint. Alguns recursos rejeitam deliberadamente métodos que são inseguros, incompatíveis ou estão fora da interface documentada.

O código de status, sozinho, não consegue identificar qual camada ou regra causou a resposta. Confirme o método, os cabeçalhos, os logs e as alterações recentes antes de modificar o sistema.

Como corrigir

Se você é visitante ou consumidor de uma API

1. Confirme a URL exata e se o cliente está enviando o método pretendido. Uma requisição feita normalmente pela barra de endereços do navegador usa GET, enquanto um cliente de API pode usar POST, PUT, PATCH, DELETE ou outro método.
2. Verifique nos cabeçalhos da resposta se há um cabeçalho Allow e informações sobre redirecionamento, autenticação, cache ou proxy. Não considere outro método uma solução válida sem que a documentação do site ou da API informe que ele é compatível.
3. Se o endpoint exigir uma conta, faça login pelo processo normal e tente novamente sem expor credenciais em uma solicitação de suporte.
4. Evite novas tentativas repetidas quando o serviço também estiver informando limites de requisições, timeouts ou sinais de sobrecarga.
5. Se o problema persistir, envie ao proprietário do site a URL, o método, o horário, o código de status e os cabeçalhos relevantes devidamente sanitizados. Não compartilhe senhas, cookies, tokens de autorização ou segredos de API.

Se você é proprietário ou responsável pela manutenção do site

1. Capture uma reprodução mínima. Registre o método, a URL, o host, o caminho da requisição, o status e os cabeçalhos relevantes da resposta exatos. Preserve o corpo da requisição somente se ele não contiver segredos ou dados pessoais.
2. Verifique se a resposta é intencional. Compare a requisição com a rota ou o contrato da API. Determine se o recurso deveria aceitar esse método e se um cabeçalho Allow identifica os métodos aceitos.
3. Identifique a camada que respondeu. Use cabeçalhos da resposta, IDs de requisição e horários para determinar se a resposta veio da aplicação, do servidor web, do proxy reverso, da CDN ou do WAF. Uma resposta gerada pelo proxy pode nunca chegar à origem.
4. Examine os logs correspondentes. Pesquise na camada identificada e, quando disponível, na camada upstream, usando o mesmo horário, caminho, método e ID de requisição. Procure incompatibilidades de rota, filtros de método, requisições rejeitadas pelo upstream e alterações recentes de política.
5. Compare as alterações recentes. Revise implantações, definições de rotas, regras do servidor web, comportamento do proxy ou da CDN, configuração de autenticação e políticas do WAF. Compare um método que falha com um método conhecido como compatível para a mesma rota.
6. Aplique a correção autorizada mais específica possível. Atualize somente a rota ou a regra que deveria aceitar o método. Não desative amplamente a autenticação, as proteções do WAF ou as restrições de método apenas para fazer o erro desaparecer.
7. Teste novamente com segurança. Repita a mesma requisição em um ambiente que não seja de produção quando possível e, em seguida, teste a rota de produção afetada seguindo o processo de alteração aprovado. Confirme que os métodos incompatíveis continuam sendo rejeitados e que as rotas relacionadas ainda retornam os códigos de status esperados.
8. Verifique caches e intermediários. Se o comportamento variar entre clientes ou locais, verifique se um proxy ou CDN armazenou a resposta em cache ou está aplicando uma regra separada. Limpe o cache ou altere seu comportamento somente conforme o procedimento operacional normal do serviço.

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

• Defina e documente os métodos compatíveis com rotas web e endpoints de API importantes.
• Teste métodos representativos para rotas críticas após alterações na aplicação, no servidor, no proxy, na CDN ou no WAF.
• Monitore as taxas de códigos de status por rota e método, em vez de tratar todas as respostas 4xx como um único grupo.
• Mantenha o roteamento, as restrições de método, a autenticação e a configuração do proxy sob controle de versão.
• Preserve IDs de requisição e logs nas camadas intermediárias e de origem por tempo suficiente para correlacionar falhas.
• Documente respostas 405 intencionais para que as equipes de suporte e monitoramento possam distinguir o comportamento esperado de regressões.
• Evite permissões amplas de métodos; permita somente os métodos exigidos por cada recurso e pelo contrato da aplicação.

Perguntas frequentes