Erro 405 Method Not Allowed

A RFC 9110, seção 15.5.6, define o 405 como um método que o servidor conhece, mas o recurso não aceita, e torna o cabeçalho Allow obrigatório: a resposta precisa listar os métodos que o recurso aceita. Um método que o servidor nem reconhece, como um PSOT digitado errado, é caso de 501.

Os frameworks variam em enviar ou não. O ServeMux do Go 1.22+ responde 405 com Allow automaticamente quando o caminho casa mas o método não, e o mesmo fazem os route handlers do Next.js para métodos que o arquivo não exporta, e o FastAPI. O Express não: um método sem rota cai no 404 padrão "Cannot POST /caminho".

O 405 pode ser guardado em cache de forma heurística, o que pega muita gente depois de um deploy. Se uma CDN guardou o 405 de uma URL antes de você criar o handler de POST, ela pode continuar servindo o erro antigo até a entrada expirar ou você limpar o cache.

Se você está visitando o site

• Você enviou um formulário de uma página salva ou em cache, e o site não aceita mais envios naquele endereço.
• Você atualizou a página logo depois de enviar um formulário e o navegador reenviou o POST para uma URL que só aceita GET.

Se você administra o servidor

• Um formulário ou fetch faz POST num arquivo estático: o nginx responde 405 a POST em conteúdo estático, porque só entrega arquivos para GET e HEAD.
• Falta o handler da rota para aquele método, como um route.ts do Next.js que exporta GET enquanto o cliente chama PUT.
• Um redirecionamento de barra final (301 ou 302) transformou o POST em GET, ou o cliente seguiu um redirecionamento para um endpoint que espera outro método.
• A hospedagem ou um WAF bloqueia PUT, DELETE ou PATCH por padrão, como fazem algumas hospedagens compartilhadas.

Se você está visitando o site

• Volte ao site, abra a página do formulário pelo endereço dela e envie de novo.
• Não atualize uma página de resultado de formulário; navegue até ela de novo.

Se você administra o servidor

• Leia o cabeçalho Allow da resposta (curl -i -X POST https://exemplo.com/caminho) para ver quais métodos o servidor aceita e ajuste o cliente.
• Crie o handler que falta, ou aponte o action do formulário para o endpoint que processa o envio, não para uma página estática.
• Use 307 ou 308 em redirecionamentos na frente de endpoints POST, para o método ser preservado, ou faça o cliente chamar a URL canônica direto.
• Limpe o cache da CDN para a URL depois de liberar um método.

O ServeMux do Go 1.22+, os route handlers do Next.js e o FastAPI já enviam 405 com Allow quando o caminho casa mas o método não; os exemplos mostram uma recusa explícita. No nginx, limit_except com deny all responde 403, não 405.

app.delete('/invoices/:id', (req, res) => {
  res.set('Allow', 'GET, HEAD');
  res.status(405).json({ error: 'Invoices cannot be deleted, only voided' });
});

// app/invoices/[id]/route.ts
export async function DELETE() {
  return Response.json(
    { error: 'Invoices cannot be deleted, only voided' },
    { status: 405, headers: { 'Allow': 'GET, HEAD' } }
  );
}

mux.HandleFunc("DELETE /invoices/{id}", func(w http.ResponseWriter, r *http.Request) {
	w.Header().Set("Allow", "GET, HEAD")
	w.Header().Set("Content-Type", "application/json")
	w.WriteHeader(http.StatusMethodNotAllowed) // 405
	w.Write([]byte(`{"error":"Invoices cannot be deleted, only voided"}`))
})

from fastapi import FastAPI, HTTPException

app = FastAPI()

@app.delete("/invoices/{id}")
def delete_invoice(id: str):
    raise HTTPException(status_code=405, detail="Invoices cannot be deleted, only voided", headers={"Allow": "GET, HEAD"})

location /api/reports/ {
  if ($request_method !~ ^(GET|HEAD)$) {
    add_header Allow "GET, HEAD" always;
    return 405;
  }
  proxy_pass http://app;
}

405 vs 501

O 501 indica que o servidor nem reconhece o método; o 405 indica que ele conhece o método, mas este recurso não o permite.

405 vs 404

O Express e outros frameworks respondem 404 para um caminho conhecido com método sem handler, quando o 405 seria o mais preciso.

405 vs 403

O 403 recusa o pedido por política; o 405 recusa só o método, e o Allow mostra o que funcionaria.

Por que o nginx devolve 405 Not Allowed em pedidos POST?

O pedido caiu numa location que serve arquivos estáticos, e o nginx só entrega arquivos para GET e HEAD. Encaminhe o caminho para a aplicação (proxy_pass ou fastcgi_pass) ou aponte o formulário para o endpoint certo.

O cabeçalho Allow é obrigatório no 405?

Sim. A RFC 9110 diz que o servidor DEVE gerar um Allow com os métodos que o recurso aceita no momento. Ele pode vir vazio se o recurso não aceitar nenhum método.

Por que recebo 405 num route handler do Next.js?

O arquivo route.ts não exporta uma função para aquele método. Exporte uma função async com o nome do método, como POST ou DELETE, e o Next.js passa a rotear.

Devo responder 405 ou 404 para um método sem suporte?

Responda 405 com Allow quando o caminho existe; isso diz ao cliente exatamente como corrigir a chamada. Use 404 só quando o caminho não existe, ou quando você não quer revelar que existe.