401 Unauthorized: o que significa e como corrigir

O que significa 401 Unauthorized

A RFC 9110 define o 401 como uma requisição que exige autenticação, seja porque nenhuma foi enviada ou porque a que foi enviada não passou. Uma resposta 401 precisa incluir um cabeçalho WWW-Authenticate nomeando o esquema que o servidor espera, como Basic, Bearer ou Digest. Esse cabeçalho é a pista que a maioria das pessoas pula: ele diz exatamente que tipo de credencial o servidor quer, o que geralmente é mais rápido do que tentar adivinhar.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="api", error="invalid_token"

Como o erro aparece

No navegador, um 401 protegido por autenticação HTTP Basic dispara o prompt nativo de usuário e senha, não uma página renderizada pelo site. Já um 401 de uma API JSON normalmente só aparece em uma aba de rede ou em um aviso que a própria aplicação construiu para isso, já que não existe uma interface padrão do navegador para uma falha de token Bearer. Na linha de comando, a credencial e o cabeçalho aparecem juntos em uma requisição:

curl -i -H "Authorization: Bearer eyJhbGciOi..." https://api.example.com/v1/account
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_token", error_description="token is expired"

Os logs do servidor e da aplicação normalmente também registram o motivo, por exemplo "token expirado", "assinatura inválida" ou "sem cabeçalho Authorization", o que reduz a causa mais rápido do que só o código de status genérico.

O que causa um 401 Unauthorized

Mais ou menos na ordem de frequência com que cada uma acaba sendo a causa:

• Nenhuma credencial enviada. Uma sessão deslogada, uma chave de API ausente, ou um cliente que nunca anexou o cabeçalho Authorization em primeiro lugar.
• Um token expirado. Cookies de sessão, tokens de acesso OAuth e JWTs carregam um tempo de vida, e um cliente usando um antigo recebe 401 mesmo que tenha funcionado minutos antes.
• Diferença de relógio entre cliente e servidor. As claims exp e nbf de um JWT são avaliadas contra o relógio do servidor. Um servidor ou cliente com a hora errada pode rejeitar um token que, pela própria conta do token, ainda é válido, ou aceitar um que já expirou.
• O esquema de autenticação errado. Enviar Authorization: Basic ... para um endpoint que espera Bearer, ou o contrário, falha mesmo com um cabeçalho presente.
• Uma chave de API colocada no lugar errado. Algumas APIs esperam a chave em um cabeçalho customizado como X-API-Key, outras em Authorization, e outras como parâmetro de query. Colocar uma chave válida no lugar errado fica idêntico a não enviar chave nenhuma.
• Um proxy reverso ou gateway removendo o cabeçalho Authorization. Algumas configurações de proxy e CDN descartam cabeçalhos que não são explicitamente repassados, e uma credencial perfeitamente válida nunca chega até a origem.
• Credenciais revogadas. Um usuário trocou a senha, um administrador rotacionou uma chave de API, ou um token foi explicitamente invalidado no logout.

401 contra 403

Os dois são frequentemente confundidos porque ambos recusam a requisição, mas a especificação traça uma linha clara. Um 401 significa que o servidor precisa que você se autentique, e uma credencial válida poderia mudar o resultado; ele precisa trazer o WWW-Authenticate. Um 403 significa que o servidor entendeu exatamente quem você é e está recusando mesmo assim, por um motivo que autenticação não resolve, como uma restrição de papel ou de plano. Se fazer login de novo plausivelmente ajudaria, deveria ser 401. Se o usuário já está logado e simplesmente não tem permissão, deveria ser 403, embora na prática muitas APIs usem 401 de forma solta para os dois casos.

Como saber de quem é a culpa

Se você é quem está chamando a API, reproduza a requisição com uma credencial nova de um ambiente limpo; se um token recém-emitido funcionar, o antigo simplesmente expirou ou foi revogado. Se um token novinho também falhar, confira o esquema e o nome do cabeçalho contra a documentação da API antes de assumir que o servidor está quebrado. Se você opera o serviço e usuários relatam 401 que você não consegue reproduzir com a sua própria conta, a forma mais rápida de separar "o servidor está bem, tokens individuais estão vencidos" de "a autenticação em si está quebrada para todo mundo" é rodar uma verificação HTTP com uma credencial válida a partir de várias localidades ao mesmo tempo e comparar os resultados.

Como corrigir um 401 Unauthorized

Se você é um visitante

1. Faça login de novo. A maioria dos 401 de uma aplicação web é simplesmente uma sessão expirada, e entrar de novo renova ela.
2. Confira o relógio do sistema no seu dispositivo se o mesmo login continua falhando logo depois que você se autentica. Um relógio vários minutos errado pode invalidar tokens baseados em tempo em alguns clientes.
3. Regenere uma chave de API ou token nas configurações da conta se você suspeitar que foi rotacionado ou revogado, em vez de assumir que o seu código de integração tem um bug.
4. Confirme se o cabeçalho Authorization está mesmo sendo enviado, usando a aba de rede do navegador ou uma chamada simples de curl, já que algumas bibliotecas de cliente HTTP descartam cabeçalhos personalizados silenciosamente em um redirecionamento.

Se você administra o site

1. Leia o cabeçalho WWW-Authenticate e os seus próprios logs em busca do motivo específico da rejeição antes de mudar qualquer coisa; "expirado", "assinatura inválida" e "cabeçalho ausente" apontam cada um para uma correção diferente.
2. Verifique a sincronização de relógio nos servidores que emitem e validam tokens. Desvio de NTP em qualquer um dos lados é uma causa clássica e intermitente de rejeições de JWT que de outra forma parecem aleatórias.
3. Confirme que o proxy ou o balanceador de carga repassa o cabeçalho Authorization. Uma regra adicionada por um motivo não relacionado pode removê-lo silenciosamente de toda requisição atrás daquele ponto.
4. Documente claramente o esquema e o nome do cabeçalho esperados na sua documentação de API, e devolva uma error_description específica no cabeçalho WWW-Authenticate para que integradores não precisem adivinhar.
5. Diferencie 401 de 403 nas suas próprias respostas onde isso importar para os chamadores, para que o código do cliente consiga distinguir "renove o seu token" de "você nunca vai ter permissão para isso".

Como prevenir uma queda silenciosa por 401

Um 401 causado por um certificado de assinatura expirado, um relógio que saiu de sincronia, ou uma mudança de proxy que passou a descartar o cabeçalho Authorization não vai parecer uma queda. O serviço responde na hora e corretamente segundo as próprias regras, então pode ficar quebrado para todo chamador até alguém perceber. Uma verificação HTTP com uma asserção no código de status esperado, rodada com uma credencial válida contra um endpoint autenticado, pega isso no momento em que começa a acontecer. Para APIs especificamente, combinar isso com monitoramento de API que confere o corpo da resposta além do código de status também pega um token que autentica mas devolve dados malformados.

Erros relacionados

Veja 403 Forbidden para requisições que o servidor entendeu e recusou independentemente das credenciais, a visão geral dos 4xx para a família mais ampla de erros de cliente, e os outros guias deste lote: 405 Method Not Allowed, 422 Unprocessable Content.

Perguntas frequentes

Por que recebo 401 logo depois de fazer login com sucesso?

Geralmente uma diferença de relógio entre o seu dispositivo e o servidor, ou um cliente que guardou em cache o token antigo, agora inválido, em vez de usar o recém-emitido. Confirme se a hora do seu sistema está correta e se o token novo está mesmo sendo enviado.

Um 401 significa que a minha conta foi invadida?

Não sozinho. Quase sempre significa uma sessão expirada, uma chave revogada, ou um cabeçalho enviado incorretamente. Só trate como um problema de segurança se você não esperava que a credencial parasse de funcionar e não consegue explicar por quê.

Qual é a diferença entre 401 e uma falha de autenticação na camada TLS?

Uma falha de certificado de cliente TLS impede que a conexão sequer seja estabelecida, então nenhum código de status HTTP é devolvido. Um 401 significa que a conexão teve sucesso e o servidor recebeu uma requisição HTTP completa, e depois a rejeitou na camada de aplicação por falta de credenciais válidas.

Um formulário de login deveria devolver 401?

Não. Um endpoint de login avaliando um usuário e senha não está autenticando uma requisição existente; uma senha errada ali é convencionalmente um 400 ou um 200 com um payload de erro, já que o propósito inteiro do endpoint é aceitar tentativas não autenticadas e julgá-las.

Uma chave de API válida ainda pode produzir 401?

Sim, se ela for enviada no cabeçalho errado ou no esquema errado, se foi rotacionada depois que a sua integração guardou a antiga em cache, ou se a requisição passou por um proxy que removeu o cabeçalho antes de repassá-la.