Código de status HTTP · Erros do servidor (5xx)
Erro 501 Not Implemented
O erro 501 Not Implemented significa que o servidor não suporta a funcionalidade que o pedido exige, geralmente um método HTTP que ele não reconhece para nenhuma URL. A causa mais comum é o cliente mandar um método como PATCH, PROPFIND ou um verbo personalizado para um servidor que nunca o implementou.
| Classe | 5xx, Erros do servidor |
|---|---|
| Definido em | RFC 9110 §15.6.2 |
| Pode ir para o cache por padrão | Sim, de forma heurística; um dos poucos 5xx que a RFC 9110 deixa o cache reaproveitar sem cabeçalhos explícitos |
| Pode repetir o pedido | Não; o servidor não tem o recurso, só outro método ou codificação resolve |
| Cabeçalhos relevantes |
|
O que significa o 501
A RFC 9110, seção 15.6.2, diz que o 501 é a resposta adequada quando o servidor não reconhece o método do pedido e não consegue suportá-lo em recurso nenhum. Esse alcance é a diferença para o 405 Method Not Allowed, que diz que aquela URL específica recusa um método que outras URLs do mesmo servidor podem aceitar.
O outro lugar onde o 501 aparece é na camada do protocolo. A RFC 9112 manda o servidor responder 501 quando o pedido usa uma transfer coding que ele não entende, e o net/http do Go faz exatamente isso: responde "501 Not Implemented" com o corpo "Unsupported transfer encoding" antes do seu handler rodar.
Ele também é um dos poucos erros de servidor que a RFC 9110 considera armazenáveis em cache de forma heurística, já que o recurso ausente não vai aparecer no próximo pedido.
Quando usar
- Um método que o seu servidor não implementa em lugar nenhum, por exemplo um verbo do WebDAV enviado para uma API REST comum.
- Um endpoint provisório de uma funcionalidade planejada mas ainda não construída, quando você quer que o cliente entenda "limitação do servidor" e não "seu pedido está errado".
Causas comuns
Se você está visitando o site
- Raro no navegador. Normalmente aparece por meio de uma ferramenta ou aplicativo que usa um método que o site nunca suportou, como um cliente WebDAV apontado para um site comum.
Se você administra o servidor
- Um cliente, SDK ou proxy envia um método para o qual o seu framework não tem rota em lugar nenhum, e você mapeia isso para 501.
- O pedido chega com Transfer-Encoding diferente de chunked, e a biblioteca HTTP do servidor recusa com 501.
- Um API gateway ou balanceador gerenciado que não suporta certo método, como o TRACE nos Application Load Balancers da AWS.
Como resolver
Se você está visitando o site
- Use o site num navegador comum, ou confira se a ferramenta está configurada para o tipo certo de servidor; nada do seu lado vai fazer o servidor suportar o método.
Se você administra o servidor
- Confira o método no log de acesso. Se ele deveria ser aceito, crie a rota; se só deve ser recusado em alguns caminhos, troque para 405 com cabeçalho Allow.
- Nos erros de Transfer-Encoding, faça o cliente mandar chunked ou Content-Length; não afrouxe a verificação do servidor, porque enquadramento ambíguo é justamente como funciona o request smuggling.
- Documente quais métodos a API aceita e responda às requisições OPTIONS de acordo.
Como enviar um 501
const SUPPORTED = new Set(['GET', 'HEAD', 'POST', 'PUT', 'DELETE', 'OPTIONS']);
// Before the routes: refuse methods the whole server does not know
app.use((req, res, next) => {
if (SUPPORTED.has(req.method)) return next();
res.status(501).json({ error: req.method + ' is not implemented' });
});// app/reports/[id]/route.ts
export async function PATCH() {
return Response.json(
{ error: 'PATCH is not implemented on this server' },
{ status: 501 }
);
}mux.HandleFunc("PATCH /reports/{id}", func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(http.StatusNotImplemented) // 501
w.Write([]byte(`{"error":"PATCH is not implemented on this server"}`))
})from fastapi import FastAPI, HTTPException
app = FastAPI()
@app.patch("/reports/{id}")
def patch_report(id: str):
raise HTTPException(status_code=501, detail="PATCH is not implemented on this server")Costuma ser confundido com
- 501 vs 405
- O 405 indica que esta URL não aceita o método, embora o servidor o conheça, e precisa listar os permitidos no Allow; o 501 indica que o servidor não suporta o método em lugar nenhum.
- 501 vs 505
- O 505 recusa a versão HTTP da linha de requisição; o 501 recusa o método ou um recurso dentro de uma versão que o servidor fala.
Perguntas frequentes
- Qual a diferença entre 501 e 405?
- O 405 Method Not Allowed vale para um recurso: o servidor conhece o método, mas esta URL recusa, e a resposta lista os métodos permitidos no Allow. O 501 Not Implemented vale para o servidor inteiro: o método ou recurso não é suportado em URL nenhuma.
- Posso usar 501 para um endpoint da API que ainda não está pronto?
- Pode, e fica mais claro que um 404, porque diz ao cliente que a URL está certa mas o servidor ainda não faz aquilo. Como o 501 pode ir para o cache de forma heurística, mande Cache-Control: no-store no endpoint provisório.
- O erro 501 é temporário?
- Não no sentido comum. Ele indica uma funcionalidade ausente, então repetir o mesmo pedido continua falhando até o servidor ser atualizado ou o cliente usar outro método ou codificação.
Revisado em por Arielton Oberek.