405 Method Not Allowed: causas e correções

O que significa 405 Method Not Allowed

A RFC 9110 exige que uma resposta 405 inclua um cabeçalho Allow listando os métodos que o recurso realmente suporta. Esse cabeçalho é o diagnóstico inteiro em uma linha: se uma requisição para /api/users devolve 405 com Allow: GET, HEAD, a rota existe e funciona bem para leitura, ela simplesmente nunca teve um manipulador conectado para o método que você enviou.

HTTP/1.1 405 Method Not Allowed
Allow: GET, HEAD

Como o erro aparece

Navegadores mostram uma página de erro genérica para um 405 devolvido em uma navegação normal, já que não é um caso que eles tratam de forma especial. É muito mais comum encontrar um 405 em uma aba de rede, uma chamada AJAX que falhou, ou uma falha de preflight CORS no console, porque a maioria dos 405 vem de requisições feitas por script em vez de links clicados. Na linha de comando, o método e o cabeçalho Allow contam toda a história:

curl -i -X POST https://example.com/downloads/report.pdf
HTTP/1.1 405 Method Not Allowed
Allow: GET, HEAD

O que causa um 405 Method Not Allowed

• Enviar POST para um arquivo estático. Uma requisição para um arquivo real em disco, como um PDF ou uma imagem, servido por um servidor web que só responde GET e HEAD para conteúdo estático.
• Chamar uma rota que só define alguns métodos. Uma rota registrada só para GET em um framework devolve 405 para qualquer outro verbo, por design, em vez de 404.
• Um preflight OPTIONS de CORS rejeitado. Navegadores enviam automaticamente uma requisição OPTIONS antes de certas chamadas cross-origin, e um servidor ou gateway sem manipulador para OPTIONS naquele caminho responde 405, o que depois aparece no navegador como uma requisição cross-origin bloqueada em vez de um 405 claro.
• nginx servindo um bloco de localização feito para arquivos estáticos. Um bloco location usando try_files contra o sistema de arquivos sem proxy_pass vai dar 405 em POST, já que servir arquivos estáticos no nginx só implementa GET, HEAD e, por padrão, um conjunto limitado de métodos.
• Restrições de verbo do WebDAV e do IIS. O IIS e alguns servidores com WebDAV habilitado listam explicitamente os verbos permitidos por caminho, e um método fora dessa lista, incluindo verbos customizados como PROPFIND, recebe 405 mesmo que a rota em geral funcione.
• Configuração incorreta de rota no framework. Uma rota pensada para aceitar GET e POST mas registrada só para um deles, geralmente depois de uma refatoração que dividiu um manipulador sem atualizar a declaração da rota.
• Uma lista de métodos permitidos no balanceador de carga ou API gateway. Alguns gateways restringem métodos permitidos por rota independentemente da aplicação, e a aplicação nunca chega a ver a requisição rejeitada.

Como saber de quem é a culpa

Um 405 é quase sempre um problema de configuração ou de código do lado do servidor, e não algo que um visitante causou, já que navegadores e links normais não enviam métodos arbitrários por conta própria. Se uma página em geral funciona mas uma ação específica, como um envio de formulário ou uma chamada de API do lado do cliente, falha com 405, verifique se o método dessa requisição específica bate com o que o endpoint espera. Se bater e o erro for novo, a forma mais rápida de confirmar que uma rota ou configuração de proxy quebrou é rodar uma verificação HTTP que envia exatamente o método que a sua aplicação usa e comparar o resultado com um deploy recente.

Como corrigir um 405 Method Not Allowed

Se você é um visitante

1. Recarregue e tente a ação de novo, já que um 405 de um envio de formulário às vezes vem de uma página que carregou uma versão em cache desatualizada do formulário apontando para o endpoint errado.
2. Limpe o cache do navegador para o site se o problema persistir, caso um service worker ou uma resposta em cache desatualizados estejam reproduzindo uma requisição antiga, agora incompatível.
3. Avise o site, já que isso é uma questão de configuração do lado deles em praticamente todo caso; não existe correção do lado do cliente para um servidor que genuinamente não aceita o método.

Se você administra o site

1. Leia o cabeçalho Allow da sua própria resposta 405 para confirmar exatamente quais métodos o servidor considera válidos para aquele caminho, depois compare com o que o cliente está realmente enviando.
2. Adicione o método que falta à rota. Na maioria dos frameworks isso é uma declaração de rota de uma linha; a correção raramente está na lógica da aplicação depois que você sabe qual verbo está faltando.
3. Trate OPTIONS explicitamente para rotas com CORS habilitado. Deixe o middleware de CORS do seu framework responder ao preflight automaticamente, ou adicione um manipulador que devolva os cabeçalhos Allow e Access-Control-Allow-Methods corretos.
4. Corrija o bloco de localização do nginx se um bloco para arquivo estático estiver interceptando uma rota que precisa de um backend. Um exemplo mínimo que encaminha o POST em vez de servi-lo como arquivo:

   location /api/ {
       proxy_pass http://backend;
   }

5. Verifique listas de métodos permitidos no gateway e no balanceador de carga separadamente da aplicação, já que uma requisição pode ser rejeitada antes de chegar ao seu código, e os logs da aplicação não vão mostrar nada sobre ela.

Como prevenir um 405 silencioso depois de um deploy

Uma rota que perde um método durante uma refatoração, ou uma regra de proxy que passa a interceptar um caminho que antes não interceptava, não vai lançar exceção nenhuma, vai só devolver uma resposta HTTP válida mas errada. Uma verificação HTTP agendada com uma asserção no código de status, enviada com o método exato que a sua integração usa, pega essa regressão logo depois do deploy que a causou, em vez de esperar que usuários relatem formulários quebrados. Para endpoints de API especificamente, monitoramento de API que confere tanto o método quanto o corpo da resposta confirma que a rota não só aceita a requisição como continua se comportando corretamente.

Erros relacionados

Veja 404 Not Found para um caminho que não existe de jeito nenhum, ao contrário de um que existe mas rejeita o método, a visão geral dos 4xx para a família completa, e 401 Unauthorized e 422 Unprocessable Content em outros pontos deste lote.

Perguntas frequentes

Qual é a diferença entre 404 e 405?

404 significa que nada existe naquele caminho para nenhum método. 405 significa que o caminho existe e funciona para pelo menos um método, só não o que você usou, e o cabeçalho Allow confirma quais métodos são válidos.

Por que uma requisição CORS falha com algo parecido a um 405?

Navegadores enviam automaticamente um preflight OPTIONS antes de muitas requisições cross-origin. Se o servidor não tem manipulador para OPTIONS naquela rota, ele responde 405, e o navegador relata isso como uma falha de CORS no console em vez de mostrar o código de status bruto diretamente.

O 405 alguma vez é a resposta correta de propósito para uma API?

Sim. Se um recurso genuinamente só suporta leitura, devolver 405 para um PUT ou DELETE contra ele é comportamento REST correto, e é mais informativo para quem chama do que um 404 genérico seria.

Um firewall ou WAF pode causar um 405?

É menos comum do que uma configuração incorreta de aplicação ou proxy, mas alguns conjuntos de regras de WAF restringem métodos permitidos por caminho e vão responder 405 ou algo parecido antes mesmo de a requisição chegar à origem.

Por que o cabeçalho Allow às vezes lista métodos que ainda falham?

O cabeçalho Allow reflete para o que a rota está registrada, não necessariamente o que está totalmente implementado. Um método pode estar declarado e ainda devolver um erro por outros motivos, como autorização ausente, depois de passar pela verificação de método.