A autenticação está ausente ou é inválida.
Quando usar
Nenhum token, ou um token expirado. Apesar do nome, significa “não autenticado”.
Causas comuns e soluções
Causas usuais: nenhum cabeçalho Authorization, um cabeçalho malformado, como um token sem o prefixo Bearer, um access token expirado, um token emitido para outro ambiente ou audience, ou diferença de relógio que faz um JWT parecer expirado ou ainda não válido. Decodifique o JWT e verifique exp, nbf, aud e iss. Um 401 correto inclui WWW-Authenticate, indicando o esquema que o servidor espera.
Os clientes devem renovar o token uma vez e tentar de novo, não entrar em loop. Cabeçalhos se perdem no caminho: navegadores e o curl descartam o Authorization em redirecionamentos para outro host, e o Apache com PHP-FPM ou CGI o remove, a menos que CGIPassAuth On esteja definido. Se um preflight CORS falha com 401, seu servidor exige autenticação no OPTIONS; preflights nunca levam credenciais, então deixe-os passar. Use 403 quando o usuário é conhecido, mas não tem permissão.
Erro do cliente (4xx)
Os códigos 4xx são erros do cliente: a própria requisição está errada, não está autorizada ou aponta para algo que não existe. Repetir a mesma requisição não vai adiantar.
Como fica
HTTP/1.1 401 UnauthorizedComo enviar
| Node.js / Express | res.status(401).end() |
|---|---|
| Python / Flask | return '', 401 |
| nginx | return 401; |
Como verificar
curl -s -o /dev/null -w "%{http_code}\n" https://example.com/