Erro 403 Forbidden: causas e como resolver no site ou na API

O erro 403 Forbidden informa que o servidor entendeu a requisição e recusou executá-la. Diferentemente do 401, repetir o login não resolve necessariamente: a identidade pode estar válida, mas sem permissão para aquele recurso ou ação.

Resposta direta: como resolver o erro 403

Descubra qual camada produziu a resposta. Confira corpo e cabeçalhos, compare uma requisição autorizada, valide papel e escopo do usuário, regras da aplicação, permissões de arquivo, configuração do servidor, WAF e CDN. Mude apenas a regra responsável e teste novamente com uma conta permitida e outra proibida.

Passo 1: capture a resposta completa

curl -i https://api.exemplo.com/relatorios \
  -H "Authorization: Bearer SEU_TOKEN"

Não compartilhe tokens em chamados ou capturas. Anote status, mensagem, request-id, servidor e cabeçalhos do proxy. Uma página gerada pela CDN tem aparência diferente de um JSON criado pela aplicação.

Passo 2: diferencie autenticação e autorização

Um token expirado ou ausente normalmente deveria causar 401 e incluir WWW-Authenticate. Um token válido sem o papel exigido causa 403. Inspecione issuer, audience, expiração e scopes sem registrar o segredo completo. Na aplicação, autorize no servidor; ocultar um botão no front-end não protege a operação.

Exemplo de decisão:

autenticado? não -> 401
autenticado? sim, possui reports:read? não -> 403
possui permissão? sim -> executar e responder 200

Passo 3: verifique Nginx e sistema de arquivos

O processo do servidor precisa atravessar os diretórios e ler os arquivos publicados. Em Linux, confira sem aplicar permissões amplas:

namei -l /var/www/site/public/index.html
sudo nginx -T
sudo tail -n 100 /var/log/nginx/error.log

Evite chmod 777. Corrija proprietário, grupo e permissões mínimas. Verifique também regras deny, autenticação básica, ausência de arquivo index e blocos location mais específicos.

Passo 4: avalie WAF, CDN e rate limit

Procure o evento pelo identificador da resposta. Regras gerenciadas podem bloquear payload, método, IP, cabeçalho ou padrão interpretado como ataque. Crie exceção estreita para rota e condição comprovadas; não desligue o firewall inteiro.

Passo 5: revise CORS apenas quando for o caso

CORS é uma política do navegador e frequentemente aparece no console sem que a resposta principal seja 403. Teste a API fora do navegador. Se o preflight OPTIONS recebe 403, permita o método e os cabeçalhos necessários para origens conhecidas. O tutorial de erro de CORS aprofunda essa investigação.

Resposta segura da API

Informe o suficiente para correção pelo cliente sem revelar regras internas sensíveis:

{
  "error": "forbidden",
  "message": "Sua conta não possui permissão para esta ação",
  "requestId": "req_abc"
}

Registre no servidor usuário, tenant, ação, regra negada e request ID. Não coloque token ou dado pessoal desnecessário no log.

Checklist de correção

• reproduzir com uma requisição mínima;
• identificar a camada que gerou 403;
• validar papel, escopo, tenant e propriedade do recurso;
• conferir logs no mesmo horário e request ID;
• testar conta permitida e proibida;
• manter negação por padrão e menor privilégio;
• documentar a mudança e monitorar reincidência.

Perguntas frequentes

Limpar o cache resolve 403?

Somente se uma credencial ou resposta incorreta estiver armazenada. Em geral, o servidor continuará negando enquanto a regra permanecer.

Qual a diferença entre 401 e 403?

401 pede autenticação válida; 403 indica que a requisição conhecida não tem direito à ação.

Fontes primárias

• MDN: status 403 Forbidden
• RFC 9110: status 403
• Nginx: módulo de controle de acesso