Erro 401 Unauthorized: o que significa e como corrigir

O que é o erro 401 Unauthorized?

Um erro 401 Unauthorized significa que o servidor precisa que você prove quem é, e sua requisição não fez isso ou as credenciais enviadas foram recusadas. Sem senha, senha errada, token expirado ou chave de API ausente: tudo termina do mesmo jeito.

O padrão HTTP o define como uma requisição que "não tem credenciais de autenticação válidas para o recurso de destino", e um servidor que envia um 401 DEVE incluir um header WWW-Authenticate informando qual esquema de login aceita (RFC 9110 §15.5.2).

Em termos simples, o servidor pergunta "quem é você?" antes de deixar você entrar.

Como o erro 401 aparece

A página que você vê depende do servidor e do aplicativo:

• 401 Unauthorized — a linha de status padrão e o texto da maioria dos aplicativos
• 401 Authorization Required — o título da página 401 embutida do nginx, com "nginx" (geralmente com a versão) logo abaixo (código-fonte do nginx); servidores Apache 2.2 antigos usam as mesmas palavras
• Unauthorized · This server could not verify that you are authorized to access the document requested — a página padrão do Apache
• 401 - Unauthorized: Access is denied due to invalid credentials — IIS; a página detalhada (exibida só no próprio servidor) e o log do IIS dão o motivo como 401.1, 401.2 ou 401.3: falha de logon, configuração do servidor ou permissões de arquivo
• Uma caixa de login no navegador — quando o servidor pede autenticação HTTP Basic ou Digest ou, no IIS e em intranets de empresas, NTLM ou Negotiate
• This page isn't working · HTTP ERROR 401 — Chrome, quando a resposta 401 não traz página própria
• JSON de uma API, como {"error":{"message":"Missing Authentication header","code":401}}

Os navegadores só mostram a caixa de login para esses esquemas. APIs com tokens ("Bearer") nunca a acionam: o 401 delas volta como JSON para o aplicativo tratar. Sites com formulário de login costumam mandar o visitante sem sessão para a página de login com um redirecionamento 302, em vez de um 401.

"401 Authorization Required" no nginx

Esse título vem da página 401 embutida do nginx. Você a recebe quando um local é protegido com auth_basic e a requisição não trouxe usuário e senha, ou trouxe os errados; cancelar a caixa de login do navegador também mostra essa página.

Como visitante, recarregue e informe o usuário e a senha que o proprietário do site passou. Eles são independentes de qualquer conta do site: a autenticação Basic consulta um arquivo de senhas no servidor.

Como proprietário do site, é assim que a proteção é configurada e como manter um caminho público:

# Create the password file (htpasswd comes with apache2-utils or httpd-tools)
#   sudo htpasswd -c /etc/nginx/.htpasswd alice   # -c creates the file: leave it out when adding users

location /admin/ {
    auth_basic           "Admin area";
    auth_basic_user_file /etc/nginx/.htpasswd;
}

# Inside a protected server block, open one path to everyone
location /public/ {
    auth_basic off;
}

# Test, then reload
#   curl -I -u alice:PASSWORD https://example.com/admin/
#   sudo nginx -t && sudo systemctl reload nginx

Ainda 401 com a senha certa? Confira se o usuário está no arquivo (htpasswd -c sobrescreve o arquivo e remove os usuários anteriores) e se o aplicativo atrás do nginx não precisa também do header Authorization: o login Basic do nginx e os tokens Bearer de um aplicativo usam o mesmo header, então o aplicativo recebe as credenciais do nginx e as recusa.

401 vs 403: qual a diferença?

Os códigos 401 e 403 são muitas vezes confundidos. Em resumo: 401 significa "não sei quem você é", enquanto 403 significa "não vou deixar você entrar", seja a identidade o problema ou não.

Uma regra prática: se fornecer o usuário e a senha corretos (ou a chave de API) resolveria, o servidor deve retornar 401. Se o usuário já está autenticado mas simplesmente não tem acesso a esse recurso, o servidor deve retornar 403 Forbidden.

Causas comuns do erro 401

As causas, do lado do visitante ao lado do servidor:

• Usuário ou senha incorretos — a causa mais básica, principalmente depois de redefinir a senha
• Token de autenticação expirado — tokens JWT, tokens de acesso OAuth e cookies de sessão têm prazo de validade
• Header Authorization ausente — a requisição não incluiu nenhuma credencial
• Chave de API inválida — a chave foi revogada, rotacionada ou copiada errada
• Esquema de autenticação incorreto — o servidor espera um token Bearer mas recebeu Basic, ou o contrário
• Diferença de relógio (clock skew) — o servidor que valida um JWT e o que o emitiu (ou a sua máquina, se ela assina o JWT) discordam da hora; muitas bibliotecas não aceitam nenhuma margem
• Um CORS preflight — a verificação OPTIONS do navegador nunca leva credenciais, então um servidor que as exige responde 401 e a requisição real nem chega a ser enviada
• Uma sessão antiga — o navegador envia um cookie de sessão que o servidor já encerrou
• Algo no caminho remove o header — o Apache esconde o Authorization do PHP-FPM e de scripts CGI, a menos que você configure o contrário, o CloudFront o remove por padrão de requisições GET e HEAD, e a autenticação Basic do nginx na frente de um aplicativo fica com ele
• Credenciais bloqueadas ou revogadas — muitas tentativas falhas podem bloquear uma conta (algumas APIs respondem então com 429 Too Many Requests)

Como corrigir o erro 401 como visitante

Se você encontrar um erro 401 em um site que está tentando acessar, o problema quase sempre está relacionado às suas credenciais de login. Siga estes passos na ordem.

1. Verifique suas credenciais de login

A causa mais comum de um erro 401 é simplesmente credenciais incorretas. Se o site mostra um popup ou formulário de login, verifique novamente seu nome de usuário e senha.

Erros comuns: Caps Lock está ativado, você está usando uma senha antiga (especialmente após uma redefinição recente), ou está fazendo login na conta errada. Se você usa um gerenciador de senhas, deixe-o preencher automaticamente as credenciais para evitar erros de digitação.

2. Limpe o cache e os cookies do navegador

Seu navegador pode estar enviando um cookie de sessão expirado. Apagar os cookies do site faz com que ele peça um login novo.

No Chrome em português, abra "Excluir dados de navegação" com Ctrl+Shift+Delete (Cmd+Shift+Delete no Mac), escolha o intervalo "Todo o período" em vez de "Última hora", marque "Cookies e outros dados do site" e "Imagens e arquivos em cache" e clique em "Excluir dados". Isso desconecta você de todos os sites. Para apagar só um site: Mais → Configurações → Privacidade e segurança → Cookies de terceiros → "Ver todos os dados e as permissões do site", pesquise o nome do site e clique em Excluir. Os passos para outros navegadores (com os nomes em inglês):

Chrome, Edge, Firefox: Ctrl+Shift+Delete (Cmd+Shift+Delete on a Mac)
  → Time range: All time → Cookies and site data + Cached files → Delete / Clear
  (this signs you out of every site; the per-site option below doesn't)
Safari: Settings → Privacy → Manage Website Data → the site → Remove
One site in Chrome: the icon left of the address → Site settings → Delete data

Depois de apagar, feche o navegador por completo (não só a aba), abra-o de novo e acesse a página outra vez. Você deve ver um pedido de login novo.

3. Tente o modo anônimo ou privado

Abra a URL em uma janela anônima (Chrome) ou privada (Firefox/Safari). Isso ignora todos os cookies em cache, extensões e credenciais armazenadas.

Se a página funciona no modo anônimo mas não no navegador normal, o problema é um cookie em cache ou uma extensão do navegador interferindo na autenticação. Desative as extensões uma por uma para encontrar a culpada.

4. Verifique a URL

Confirme que você está acessando a URL certa. Alguns servidores retornam 401 em caminhos que exigem autenticação, mesmo que o caminho em si esteja errado. Você pode estar tentando entrar numa área restrita que não era para você.

Veja se existe uma versão pública da página em outra URL. Por exemplo, example.com/admin/ pode retornar 401 enquanto example.com/ é de acesso público.

Não tem certeza de que o site funciona? Experimente o Verificador de site fora do ar: ele abre o site de 11 lugares, assim você distingue um problema de login de uma queda.

Como corrigir o erro 401 como desenvolvedor

Para desenvolvedores trabalhando com APIs, erros 401 geralmente estão relacionados ao header Authorization, formato do token ou ciclo de vida das credenciais. Estas são as correções mais comuns.

5. Verifique o header Authorization

O erro mais comum entre desenvolvedores é um header Authorization mal formado. Quando o servidor envia um header WWW-Authenticate, ele indica o esquema esperado; muitas APIs JSON (como as do GitHub e do OpenRouter) o omitem e explicam o problema no corpo da resposta.

Confira se o seu header segue o formato exigido. Os esquemas mais comuns são Bearer (para tokens) e Basic (usuário:senha codificado em Base64).

# Bearer token authentication (most APIs)
curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." https://api.example.com/data

# Basic authentication (username:password in Base64)
curl -u "username:password" https://api.example.com/data
# Equivalent to:
curl -H "Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=" https://api.example.com/data

# Common mistakes that cause 401:
# Missing "Bearer " prefix:  Authorization: eyJhbGci...  ← WRONG
# Extra space:               Authorization: Bearer  eyJ... ← many servers reject it
# Wrong scheme:              Authorization: Basic eyJhbGci... ← WRONG

Depois leia o header WWW-Authenticate da resposta 401: ele indica o esquema que o servidor espera. O Verificador de headers HTTP da DNS Robot mostra a resposta completa.

6. Verifique a validade da chave de API

As chaves de API param de funcionar quando a chave é rotacionada ou revogada, a conta é suspensa ou rebaixada de plano, ou uma chave de teste é usada em produção. (Um limite de taxa responde 429, e uma chave sem acesso a um endpoint costuma receber 403.)

Confira no painel do provedor se a chave continua ativa e teste-a diretamente:

# Test a key: print only the status code (a real GET; some APIs reject HEAD)
curl -s -o /dev/null -w "%{http_code}\n" -H "Authorization: Bearer YOUR_API_KEY" https://api.example.com/me
# 200 = the key works
# 401 = the key is missing, wrong, revoked or expired
# 403 = the key works but isn't allowed to use this endpoint

# Common slips:
# 1. A space or newline after the key in .env:   API_KEY="abc123 "
# 2. The test key in production, or the reverse
# 3. An empty variable, so the header is just "Authorization: Bearer"

7. Resolva expiração e renovação de tokens

Tokens JWT e tokens de acesso OAuth têm vida limitada, geralmente de 15 minutos a 24 horas. Quando expiram, toda chamada de API retorna 401 até você obter um token novo.

Se você tem um token de atualização (OAuth 2.0 e a maioria das configurações JWT), troque-o por um novo token de acesso; se não, faça login de novo.

# Read a JWT's payload (tokens use base64url, so plain base64 -d often fails)
python3 -c 'import sys,base64,json; p=sys.argv[1].split(".")[1]; print(json.dumps(json.loads(base64.urlsafe_b64decode(p+"==")),indent=2))' "$TOKEN"
# "exp" is a Unix timestamp; compare it with: date +%s

# OAuth 2.0: get a new access token with the refresh token
curl -X POST https://auth.example.com/token \
  -d "grant_type=refresh_token" \
  -d "refresh_token=YOUR_REFRESH_TOKEN" \
  -d "client_id=YOUR_CLIENT_ID"

8. Corrija problemas de CORS preflight

Quando uma página web chama uma API de outro domínio com um header Authorization, o navegador envia antes uma requisição preflight OPTIONS, e o preflight nunca leva credenciais. Se o servidor exige autenticação no OPTIONS, ele responde 401, o preflight falha e o navegador mostra um erro de CORS: a requisição real nunca é enviada.

A solução: deixe as requisições OPTIONS passarem sem autenticação nos endpoints com CORS.

# Nginx — allow OPTIONS requests without auth
location /api/ {
    if ($request_method = OPTIONS) {
        add_header Access-Control-Allow-Origin https://app.example.com;
        add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS";
        add_header Access-Control-Allow-Headers "Authorization, Content-Type";
        add_header Access-Control-Max-Age 86400;
        return 204;
    }

    # CORS header on every other answer, the 401 included, or the browser reports a CORS error
    add_header Access-Control-Allow-Origin https://app.example.com always;

    # Normal auth for other methods
    auth_basic "Restricted";
    auth_basic_user_file /etc/nginx/.htpasswd;
}

Como corrigir o erro 401 como proprietário do site

Se seus visitantes ou usuários estão reportando erros 401, o problema está na configuração de autenticação do seu servidor. Siga estas verificações.

9. Revise a configuração de autenticação do servidor

Confira se a autenticação está ativada só nas rotas que precisam dela. Um erro comum é proteger um diretório ou site inteiro quando só alguns caminhos deveriam exigir login.

No nginx, revise as diretivas auth_basic; no Apache, AuthType e Require. No Node.js/Express, revise a ordem dos middlewares: um app.use(auth) registrado antes das rotas públicas protege essas rotas também, então registre as rotas públicas primeiro ou aplique a autenticação só ao router protegido.

# Nginx — WRONG: protects everything, including public pages
server {
    auth_basic "Restricted";
    auth_basic_user_file /etc/nginx/.htpasswd;
    # All pages now require login — including your homepage!
}

# Nginx — CORRECT: only protect admin routes
server {
    location / {
        # Public — no auth required
    }
    location /admin/ {
        auth_basic "Admin Area";
        auth_basic_user_file /etc/nginx/.htpasswd;
    }
}

10. Verifique as regras de autenticação do .htaccess

No Apache, arquivos .htaccess podem ativar a autenticação Basic ou Digest em um diretório. Se um diretório público tem um .htaccess com as diretivas AuthType e Require, todo visitante recebe um 401 com pedido de login.

Procure arquivos .htaccess no diretório afetado e em todos os diretórios acima dele: o Apache aplica as regras de todos os .htaccess do caminho.

# Find all .htaccess files with auth rules
find /var/www/html -name '.htaccess' -exec grep -l 'AuthType\|AuthUserFile\|Require valid-user' {} \;

# Example .htaccess that causes 401 for everyone:
# AuthType Basic
# AuthName "Restricted Area"
# AuthUserFile /etc/apache2/.htpasswd
# Require valid-user

# Fix: remove auth lines from public directories,
# or move them to the specific /admin/.htaccess only

11. Garanta que o header Authorization chegue ao seu aplicativo

O cliente envia credenciais corretas, mas o aplicativo nunca as vê. Onde o header se perde:

O nginx repassa o Authorization ao backend por padrão, então você não precisa de linhas extras; mas, se o mesmo local usa auth_basic, o login do nginx fica com o header (veja a seção do nginx acima). O Apache esconde o Authorization do PHP-FPM e de scripts CGI, a menos que você ative CGIPassAuth (Apache 2.4.13+), a causa clássica de 401 em APIs de WordPress e Laravel atrás do Apache.

# Apache 2.4.13+ (inside a <Directory> block, or .htaccess): pass Authorization to PHP-FPM and CGI
CGIPassAuth On

# Older Apache: copy it into an environment variable instead
SetEnvIf Authorization "(.+)" HTTP_AUTHORIZATION=$1

Depurando erros 401 com HTTP headers

O jeito mais rápido de diagnosticar um 401 é ler a resposta: o header WWW-Authenticate, quando o servidor o envia, diz qual login ele quer, e as APIs JSON costumam explicar o erro no corpo.

Use o Verificador de headers HTTP da DNS Robot (se o 401 só aparece depois de um redirecionamento, o Verificador de redirecionamento mostra qual etapa o retorna) ou o curl no terminal:

# Print the response headers of a real GET
curl -sS -D - -o /dev/null https://api.example.com/protected-endpoint

# A 401 often carries one of:
# WWW-Authenticate: Bearer realm="api", error="invalid_token"
# WWW-Authenticate: Basic realm="Admin Area"

# It tells you:
# - the scheme (Bearer, Basic, Digest, Negotiate)
# - the realm (which area is protected)
# - for Bearer tokens, the error: invalid_request, invalid_token or insufficient_scope

Se o WWW-Authenticate diz Bearer, você precisa de um token; se diz Basic, de usuário e senha. error="invalid_token" significa que o token está expirado, revogado, malformado ou inválido por outro motivo. Nenhum header? Leia o corpo da resposta: muitas APIs colocam o motivo lá.

O erro 401 afeta o SEO?

Um 401 em uma página pública a tira do Google. O Google trata todos os códigos 4xx, exceto o 429, da mesma forma: o rastreador informa que o conteúdo não existe e uma URL indexada é removida (documentação do Google sobre rastreamento).

Os 401 em páginas que devem exigir login (painéis de administração, dashboards, APIs) são normais: o Google não penaliza um site por eles. Só não use 401 ou 403 para frear o Googlebot; segundo o Google, eles não afetam a taxa de rastreamento.

O problema é um 401 em páginas que deveriam ser públicas, geralmente por uma autenticação aplicada ao site inteiro, ou por uma regra de CDN ou proxy que pede credenciais em caminhos públicos.

Como prevenir erros 401

Prevenir evita depuração depois. Siga estas práticas para reduzir os erros 401 em seus aplicativos e sites.

• Implemente a renovação automática de tokens — use tokens de atualização para obter tokens de acesso novos em silêncio antes que expirem
• Defina bem os escopos de autenticação — proteja só as rotas que realmente precisam e mantenha as páginas públicas abertas
• Use mensagens de erro claras — retorne corpos JSON úteis junto com o 401, não só o código de status
• Monitore as falhas de autenticação — configure alertas para picos de respostas 401, que podem indicar problemas de credenciais ou ataques
• Sincronize os relógios dos servidores — use NTP para manter todos os servidores a poucos segundos do UTC e evitar recusas de JWT por diferença de relógio
• Teste com o Verificador de headers HTTP — confira regularmente que as páginas públicas retornam 200 e as protegidas retornam 401, como esperado
• Documente seu esquema de autenticação — deixe claro na documentação da API o formato esperado do header Authorization
• Trate o CORS preflight — sempre permita requisições OPTIONS sem autenticação nos endpoints da API