Erro 403 no Claude Code: região, gateway, TLS ou login?

Um HTTP 403 no Claude Code, por si só, não prova que sua conta foi banida. Use o Claude Code 2.1.318 ou posterior para incluir as correções de diagnóstico, gateways e certificados descritas aqui. Depois, siga a verificação correspondente ao erro em vez de fazer login repetidamente.

As notas da versão 2.1.317 diferenciam bloqueios regionais ou de rede de falhas de login. As notas da versão 2.1.318 melhoram o tratamento de arquivos de certificados problemáticos e esclarecem os erros de logins salvos que expiraram. Essas mudanças ajudam a identificar falhas. Elas não removem restrições de acesso nem corrigem qualquer configuração de gateway.

Comece pela versão corrigida e uma solicitação pequena

Em 2026-11-10, a versão 2.1.318 é a mínima que reúne essas correções, não necessariamente a versão mais recente. Cada correção apareceu pela primeira vez nas versões abaixo.

Sintoma	Primeira versão com a correção correspondente	Primeira verificação
Um HTTP 403 causado por bloqueio regional ou de rede aparece como falha de login	2.1.317	Leia a explicação do bloqueio e identifique o serviço que respondeu
O VS Code abre a tela de login após um bloqueio regional ou de rede	2.1.317	Repita a solicitação na interface afetada do VS Code
O Auto falha a cada turno quando o gateway configurado como Base URL rejeita a verificação de segurança com 403 ou 422	2.1.317	Compare Manual e Auto; a exceção do 403 com apiKeyHelper continua válida
O erro unable to get local issuer certificate aparece após um proxy com inspeção TLS renovar seu certificado raiz	2.1.317	Verifique a cadeia de certificados aprovada e a versão do cliente
O arquivo NODE_EXTRA_CA_CERTS está vazio, não usa PEM ou começa com um certificado danificado, causando falhas nas conexões	2.1.318	Corrija o arquivo de certificados e confira os avisos na inicialização
Não é possível acessar um Claude apps gateway obrigatório	2.1.317	Verifique o caminho de rede e a confiança no certificado
Um login salvo do claude.ai atinge seu limite de validade	2.1.318	Renove o login ativo em vez de alterar a rede

No Bash, confira o CLI que você realmente usa:

claude --version
claude auth status

A referência do CLI descreve claude auth status como um relatório do estado da autenticação. Use esse resultado para verificar a autenticação configurada, não como prova de que as solicitações ao modelo funcionam.

Use o método de atualização compatível com sua instalação. Para uma instalação nativa, execute:

claude update
claude --version

Para instalações via gerenciador de pacotes ou administradas de forma centralizada, siga as instruções de instalação e atualização. Confirme que a versão exibida atende ao mínimo necessário. Repita o teste na interface que falhou: uma solicitação bem-sucedida no terminal não comprova que a conexão do VS Code funciona.

Em seguida, envie uma solicitação pequena no mesmo ambiente do Bash:

claude -p 'Reply with exactly OK. Do not use tools.'

O resultado esperado é OK, sem erro de conexão ou autenticação. Isso verifica uma solicitação básica ao modelo. Não testa o mecanismo de revisão do Auto nem comprova a compatibilidade com todas as funcionalidades.

Bloqueio regional ou de rede não é login expirado

Investigue a rede ou o motivo da recusa de acesso quando o erro indicar um bloqueio. Refazer a autenticação não é a primeira solução para esse sintoma.

O registro de mudanças da versão 2.1.317 informa, em tradução:

Corrigido um problema que exibia um bloqueio regional ou de rede (HTTP 403) como falha de login. Agora o erro explica o bloqueio.

A mesma versão corrige separadamente a abertura da tela de login do VS Code nessa situação. Nenhuma das entradas afirma que atualizar libera uma solicitação bloqueada.

Inicie o Claude Code e execute /status. Confira a rota ativa e a origem da credencial seguindo as instruções de conexão ao gateway. Antes de investigar a conta, determine se a solicitação vai diretamente para a Anthropic ou para o gateway configurado.

Em uma rede corporativa, peça à equipe de TI que confira as configurações de proxy usadas pelo processo afetado. Isso inclui HTTPS_PROXY e HTTP_PROXY, documentadas no guia de configuração de rede. Se o bloqueio regional estiver confirmado, consulte a disponibilidade do serviço com o provedor em vez de renovar credenciais repetidamente.

Guarde o corpo da resposta, o nome do host de destino, o horário e o identificador da solicitação, quando disponível. Não envie dumps do ambiente, credenciais ou prompts completos em um chamado de suporte.

Um aviso específico de suspensão da conta deve ser tratado pelo suporte de contas. A referência de erros da Anthropic identifica essa condição como uma conta suspensa. Outra possibilidade é a falta de acesso ao modelo. O guia de instalação e autenticação documenta erros 403 após uma autenticação bem-sucedida quando a conta não pode usar o modelo solicitado.

Para verificar, envie outra solicitação pequena pela rota pretendida e aprovada. Se ela ainda retornar 403, use a explicação atual e os registros do provedor para identificar a recusa. Não conclua que a conta foi banida apenas pelo código de status.

O Auto falha a cada turno por um gateway

Investigue a verificação de segurança quando o Manual funcionar, mas o Auto falhar repetidamente pelo mesmo gateway. A correção da versão 2.1.317 tem um escopo específico. Tradução da entrada:

Corrigida a falha do Auto a cada turno quando um gateway LLM definido como URL base responde 403 ou 422 à verificação de segurança no servidor. Um 403 com apiKeyHelper permanece inalterado.

A exceção importa. Um 403 com apiKeyHelper ativo não é coberto por essa mudança. Peça ao responsável pelo gateway que confira a credencial e o processo de autorização, sem expor a saída secreta do helper.

O guia de compatibilidade de gateways identifica um valor de anthropic-beta e um campo safeguards na solicitação de revisão no servidor. Se o gateway rejeitar esse recurso, a investigação será diferente daquela usada para uma credencial rejeitada. O código de status, sozinho, não distingue os dois casos.

Compare duas sessões em uma cópia de trabalho de um repositório Git confiável. Mantenha o mesmo modelo, endpoint, credenciais e tarefa.

Inicie claude --permission-mode default. Peça ao Claude que execute git status --short usando Bash e informe o resultado sem alterar arquivos. Aprove a solicitação de permissão, caso apareça.

Saia dessa sessão, inicie claude --permission-mode auto e repita a tarefa. Confirme que o modo solicitado está ativo usando os controles de modos de permissão. Uma sessão que não entrou no Auto não serve para validar esse modo.

Se apenas a sessão do Auto falhar, localize a solicitação que falhou nos registros do gateway. Peça ao operador que examine a rejeição seguindo o guia de compatibilidade. A comparação reduz o escopo da investigação, mas não prova qual regra do gateway causou a falha.

Com a aprovação do administrador, um teste temporário pode usar as solicitações do próprio classificador do Claude Code em vez da revisão no servidor:

CLAUDE_CODE_AUTO_MODE_SERVER=0 claude --permission-mode auto

A referência de variáveis de ambiente documenta esse ajuste. Ele muda onde ocorre a revisão; não desativa a verificação de permissões. O classificador continua fazendo solicitações ao modelo. Confira o consumo e a latência dessas solicitações antes de manter o ajuste.

Se essa sessão funcionar, mas o Auto sem o ajuste falhar, investigue a compatibilidade com a revisão no servidor. Se ambas falharem, investigue o erro informado de credencial, modelo ou gateway. Não presuma que essa correção se aplica.

Para entender a cobrança, consulte o faturamento do classificador no servidor e o comportamento da revisão alternativa. Não trate as solicitações separadas do classificador como uma alternativa offline ou necessariamente gratuita.

Corrija a confiança no certificado, não a autenticação

Trate unable to get local issuer certificate como um problema de confiança no certificado. Essa falha ocorre em uma camada diferente da resposta HTTP de autorização.

O registro de mudanças da versão 2.1.317 informa, em tradução:

Corrigidas falhas de solicitações à API com “unable to get local issuer certificate” atrás de alguns proxies com inspeção TLS após a renovação de um certificado raiz.

A correção cobre o problema de renovação descrito. Isso não comprova que todo erro de certificado do emissor tenha essa causa.

Primeiro, confirme a versão do cliente. Depois, pergunte à equipe de TI se o certificado raiz do proxy mudou. Confirme também qual conjunto de certificados de autoridades certificadoras o cliente deve aceitar. Use um conjunto PEM aprovado, não um certificado copiado de uma fonte não verificada.

Se o ambiente exigir um conjunto próprio, salve o arquivo fornecido pela equipe de TI como $HOME/company-ca.pem. Inicie um novo processo do Claude Code no mesmo shell Bash:

export NODE_EXTRA_CA_CERTS="$HOME/company-ca.pem"
claude -p 'Reply with exactly OK. Do not use tools.'

Isso segue a configuração documentada de CA personalizadas. O caminho do exemplo é um nome de arquivo local escolhido por você. Os certificados devem vir da sua organização.

A verificação é uma solicitação concluída sem o erro de certificado do emissor. Se ainda falhar, peça à equipe de TI que confira o conjunto fornecido e a cadeia de certificados apresentada pelo proxy.

Não defina NODE_TLS_REJECT_UNAUTHORIZED=0. As orientações da Anthropic sobre erros de certificados alertam que isso desativa a validação de certificados.

Arquivos NODE_EXTRA_CA_CERTS vazios ou danificados

Use a versão 2.1.318 ou posterior quando o próprio arquivo de CA adicionais estiver malformado. O registro de mudanças informa, em tradução:

Corrigida a falha de todas as conexões quando o arquivo NODE_EXTRA_CA_CERTS está vazio, não usa PEM ou começa com um certificado danificado. Agora os certificados legíveis são usados, com um aviso em stderr.

Confira os avisos, além do resultado final da conexão. A correção usa os certificados legíveis. Ela não repara o arquivo nem fornece um certificado ausente de que o proxy precisa.

Substitua o conjunto vazio ou danificado pelo arquivo PEM aprovado. Remova uma configuração acidental de NODE_EXTRA_CA_CERTS somente após confirmar que o ambiente não precisa dela. Depois, inicie um novo processo e repita a solicitação pequena.

Se a solicitação funcionar, mas o aviso sobre o arquivo de certificados continuar, corrija o conjunto antes de considerar a configuração concluída.

O Claude apps gateway obrigatório está inacessível

Restabeleça a conexão com o gateway obrigatório antes de alterar um login que funciona. A entrada da versão 2.1.317 informa, em tradução:

Melhorado o erro de inicialização quando um Claude apps gateway obrigatório está inacessível. Agora ele aponta para a rede, não para o login, e informa quando não é possível verificar o certificado TLS do gateway.

Essa entrada trata de um Claude apps gateway obrigatório. Não a aplique automaticamente a qualquer endpoint de terceiros configurado em ANTHROPIC_BASE_URL.

Envie ao administrador do gateway o nome do host afetado e o erro sem informações sensíveis. Peça que confira a disponibilidade do serviço, DNS, a política do proxy e a confiança no certificado. Se a mensagem indicar uma falha na verificação do certificado, siga as verificações de CA em vez de redefinir credenciais.

A verificação tem duas etapas: o Claude Code deve superar a falha de inicialização do gateway e depois concluir a solicitação pequena ao modelo. Um erro de autenticação posterior é outro resultado que precisa ser investigado.

Renove o login somente quando essa credencial tiver expirado

Renove o login salvo do claude.ai quando o erro indicar que ele expirou. As notas da versão 2.1.318 diferenciam esse caso de um bloqueio de rede. Tradução:

Corrigida a falha de login quando um login salvo do claude.ai atinge seu limite de validade. Agora a mensagem informa isso e, em claude -p, indica claude auth login e claude setup-token.

Para um fluxo interativo que deva usar seu login do claude.ai, execute estes comandos no Bash:

claude auth login
claude auth status
claude -p 'Reply with exactly OK. Do not use tools.'

Conclua o login antes de verificar o estado e enviar a solicitação. O resultado esperado é o estado de autenticação pretendido, seguido de uma resposta bem-sucedida.

A versão também indica claude setup-token para recuperar o acesso em fluxos não interativos. Siga as orientações de autenticação para esse caso em vez de inserir um token no script.

Uma credencial fornecida pelo gateway precisa ser recuperada por meio de quem a emitiu. Fazer login no claude.ai não testa essa credencial. Se o login renovado ainda produzir um erro de região, rede ou gateway, volte à verificação correspondente em vez de repetir o login.

Verifique ANTHROPIC_BASE_URL e a credencial ativa

Verifique a rota dentro da sessão que falha antes de alterar outras configurações. O guia de conexão recomenda /status para conferir o valor efetivo de Base URL e a origem da credencial.

Use o endereço base compatível com Anthropic documentado pelo gateway. O guia do protocolo associa ANTHROPIC_BASE_URL ao formato Anthropic Messages e a /v1/messages. Não copie uma URL compatível com OpenAI para essa configuração sem verificar o protocolo. O guia de diagnóstico de Base URL e endpoints explica a diferença.

Escolha a variável de credencial de acordo com o cabeçalho exigido pelo gateway. A Anthropic documenta ANTHROPIC_AUTH_TOKEN para Authorization: Bearer e ANTHROPIC_API_KEY para X-Api-Key. Siga as instruções do gateway em vez de colocar a mesma credencial em todas as variáveis disponíveis.

Para uma conexão existente pela API do BetterToken, as instruções para Claude Code usam https://bettertoken.ai, sem /v1, e ANTHROPIC_AUTH_TOKEN. Em 2026-11-10, o catálogo inclui claude-sonnet-5-5. Esse é um acesso à API separado, não uma assinatura do Claude nem uma garantia de que todas as funcionalidades do Claude Code funcionem.

Se a rota efetiva diferir da configuração pretendida, siga como verificar o provedor ativo do Claude Code. Localize uma solicitação pequena nos registros do provedor pretendido e repita a operação específica que falhou. Uma resposta básica basta para uma verificação básica de conexão. Um incidente no Auto também exige que a comparação do Auto funcione.