HTTP 401 Unauthorized: 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 de site informa 401 Unauthorized.
• Uma página protegida ou rota de API solicita login, rejeita uma sessão ou retorna um corpo de erro de autenticação.
• O mesmo host pode disponibilizar algumas URLs públicas normalmente, enquanto uma rota ou método de solicitação retorna 401.
• Uma solicitação pode receber HTTP 401 mesmo quando a resolução de DNS e a negociação de TLS estão funcionando.
• Os headers da resposta podem indicar requisitos de autenticação, redirecionamentos, comportamento de cache, um proxy ou CDN e, às vezes, um ID de solicitação ou de correlação.
• Solicitações feitas com uma sessão do navegador podem se comportar de forma diferente das solicitações feitas por um cliente de API ou serviço de monitoramento.

Causas principais, por probabilidade

1. Autenticação ausente ou inválida — A solicitação não tem credenciais, usa uma sessão expirada, um token inválido, uma senha incorreta ou um header de autorização formatado incorretamente.
2. Contexto incorreto da solicitação — O cliente está usando a URL, o método HTTP, o host, o audience, o scope, o cookie, a chave de API ou o ambiente incorreto; por isso, credenciais válidas em outro local não são aceitas aqui.
3. Regras de autenticação da aplicação — Middleware, route guards ou validação de sessão rejeitam a solicitação antes que o handler da aplicação seja executado.
4. Regras do servidor web, reverse proxy, CDN ou WAF — Uma camada de infraestrutura exige autenticação ou encaminha credenciais incompletas, alteradas ou ausentes.
5. Comportamento de cache ou roteamento — Uma resposta armazenada em cache, um redirecionamento inesperado, uma rota desatualizada ou uma incompatibilidade de host/protocolo envia o cliente a um endpoint com requisitos de autenticação diferentes.
6. Alterações na configuração upstream ou no serviço — Um deploy, uma alteração no provedor de identidade, a rotação de um secret, uma mudança no proxy ou uma divergência de ambiente faz com que solicitações antes válidas falhem.

Como corrigir

Para visitantes

1. Verifique o endereço exato e tente novamente uma vez, sem atualizar a página repetidamente.
2. Se o recurso exigir uma conta, faça login pela interface normal do site e tente novamente. Verifique se a sessão expirou.
3. Se apenas um link falhar, informe essa URL específica em vez de presumir que o site inteiro está indisponível.
4. Registre o horário aproximado, a página ou o endpoint da API e a mensagem 401 exibida. Não envie senhas, cookies, access tokens ou outros segredos.
5. Entre em contato com o proprietário do site se uma página normalmente pública retornar 401 ou se o login funcionar, mas o recurso protegido continuar inacessível.

Para clientes de API e desenvolvedores

1. Reproduza a falha com o mesmo método HTTP, URL, host, parâmetros de consulta, headers e corpo usados pelo cliente que falhou. Sempre que possível, use uma conta que não seja de produção ou uma credencial de teste.
2. Confirme que a credencial está presente, não expirou, está formatada corretamente e é destinada a este host, rota e ambiente. Verifique o scope ou o audience do token quando o sistema de autenticação os utilizar.
3. Capture o status, os headers da resposta e o corpo da resposta sem expor segredos. Preste atenção especial às informações do desafio de autenticação, aos redirecionamentos, aos headers de cache e aos IDs de solicitação.
4. Compare uma solicitação conhecida como válida com a solicitação que falha, alterando uma diferença por vez. Verifique cookies, headers de autorização, encaminhamento pelo proxy, redirecionamentos e o método da solicitação.
5. Identifique o componente que gerou a resposta: aplicação, servidor web, reverse proxy, CDN ou WAF. O corpo da resposta, headers característicos e logs específicos da camada podem ajudar a distingui-los.
6. Inspecione os logs correspondentes usando o timestamp, a rota, o cliente e o ID da solicitação. Verifique deploys recentes, alterações no provedor de identidade, rotação de secrets, atualizações de roteamento e configuração do proxy.
7. Aplique a correção autorizada mais específica possível — por exemplo, corrigir uma credencial específica da rota ou uma regra de encaminhamento — e teste novamente a mesma solicitação. Não desative a autenticação, não disponibilize respostas privadas publicamente por cache nem conceda permissões amplas como primeira medida.
8. Teste rotas públicas e protegidas relacionadas, os métodos HTTP relevantes e o comportamento não autenticado esperado para garantir que a correção não criou um problema de controle de acesso.

Diferencie 401 de falhas próximas

• 401 Unauthorized: a autenticação está ausente, é inválida ou não é aceita pelo endpoint.
• 403 Forbidden: o servidor entendeu a solicitação, mas não autorizará o acesso; uma autenticação válida ainda pode estar presente.
• 404 Not Found: a rota ou o recurso não está disponível nesse local, embora alguns sistemas ocultem intencionalmente recursos protegidos dessa forma.
• Resposta 5xx: o processamento no servidor falhou, em vez de simplesmente rejeitar a autenticação.

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

• Monitore falhas de autenticação por rota, método, tipo de cliente e deploy para distinguir um problema isolado de rota de um incidente mais amplo.
• Mantenha a configuração de autenticação, roteamento, proxy e cache sob controle de versão e revise as alterações antes da publicação.
• Teste as respostas esperadas para solicitações não autenticadas, autenticadas e com permissões insuficientes nas rotas web e nos métodos de API importantes.
• Use credenciais e configurações separadas para desenvolvimento, testes e produção; faça a rotação de secrets por meio de um processo controlado.
• Imp peça que access tokens, cookies e senhas apareçam em logs da aplicação, do proxy, do monitoramento ou do suporte.
• Preserve IDs de solicitação sanitizados, timestamps e logs específicos de cada camada por tempo suficiente para investigar falhas de autenticação.
• Documente quais rotas são intencionalmente públicas, protegidas ou restritas por método e tipo de cliente.

Perguntas frequentes