4014xx · Erro do cliente
HTTP 401 Unauthorized
O 401 Unauthorized indica falta de autenticação: o servidor não sabe quem você é, ou a credencial enviada não é válida. Apesar do nome, trata de identidade, não de permissão.
O que significa
Falta autenticação, ou ela falhou. Apesar do nome, é sobre identidade. A requisição tem algum problema — quem chamou precisa corrigir.
Quando usar
Token ausente, inválido ou expirado — mande o WWW-Authenticate.
Especificação: RFC 9110
Causas comuns
- Token ausente no header Authorization
- Token expirado
- Formato errado do header — falta o prefixo Bearer
- Chave de API de outro ambiente, como usar a de teste em produção
Como resolver
- Confira se o header está como Authorization: Bearer seguido do token
- Verifique a expiração do token e renove-o quando necessário
- Confirme que a credencial pertence ao ambiente que está sendo chamado
- No servidor, devolva o header WWW-Authenticate indicando o esquema esperado
Exemplo de resposta
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="api", error="invalid_token"
Content-Type: application/json
{"erro": "token_expirado"}Perguntas frequentes
- Qual a diferença entre 401 e 403?
- O 401 diz “não sei quem você é” — falta autenticação ou ela falhou. O 403 diz “sei quem você é e mesmo assim não pode” — a identidade é válida, mas falta permissão. Renovar o token resolve o 401, nunca o 403.
- Recebo 401 mesmo com o token certo. Por quê?
- As causas mais frequentes são formato do header sem o prefixo Bearer, token de outro ambiente e relógio dessincronizado invalidando a data de expiração.