Índice
Tentando usar o Claude Code em uma máquina corporativa ou via VPN, e ele não conecta com erros como estes?
Unable to connect to API. Check your internet connection
Unable to connect to API (ECONNREFUSED)
Unable to connect to API: SSL certificate verification failed.
Check your proxy or corporate SSL certificates
fetch failedEsses são erros de rede que significam "o Claude Code não consegue alcançar o servidor da Anthropic (api.anthropic.com)." Eles não são de autenticação (401/403), não são sobrecarga do servidor (529/500) e não são limite de taxa (429) — a requisição nunca chegou ao servidor. As causas habituais são proxies corporativos, inspeção de TLS (certificados) e firewalls, o que torna isso especialmente comum em redes corporativas. Este artigo cobre a configuração de proxy, os certificados de CA corporativa, os domínios a liberar e os passos de diagnóstico — com base em informações oficiais.
Os pontos-chave de antemão. (1) Atrás de um proxy, defina HTTPS_PROXY. (2) Para um erro de certificado causado por inspeção de TLS (Zscaler, etc.), aponte NODE_EXTRA_CA_CERTS para a CA corporativa — e nunca desative a verificação com NODE_TLS_REJECT_UNAUTHORIZED=0 (isso expõe todo o tráfego à interceptação). (3) Comece executando curl -I https://api.anthropic.com para checar "ele consegue ao menos alcançar?" — essa é a raiz da triagem.
Ele nunca chega ao servidor
— onde ele para é o que decide a solução
HTTPS_PROXYNODE_EXTRA_CA_CERTS
Primeiro execute curl -I https://api.anthropic.com para checar se ele consegue alcançar.
Quando você souber onde ele para (proxy / TLS / firewall), a configuração a aplicar fica decidida.
1. O que esse erro está te dizendo
Unable to connect to API, fetch failed, ECONNREFUSED / ETIMEDOUT significam "a requisição não chegou ao servidor da Anthropic" = ela falhou em algum ponto do TCP/TLS/DNS. Essa é a diferença decisiva em relação a outros erros: autenticação (401/403), servidor (529/500) e taxa (429) são respostas depois de alcançar o servidor, ao passo que erros de rede significam que ela nunca chegou lá.
Em redes corporativas, os bloqueios típicos se dividem em três camadas. (1) Proxy — você não pode sair diretamente e precisa rotear por um proxy corporativo que não está configurado. (2) Inspeção de TLS (certificados) — um proxy de inspeção como o Zscaler substitui os certificados, então você precisa confiar na CA raiz corporativa. (3) Firewall — os domínios necessários não estão liberados. A primeira coisa a fazer é confirmar "ele consegue alcançar?" com curl -I https://api.anthropic.com — essa única checagem separa "um problema de rede" de "todo o resto."
Onde ele para = qual configuração aplicar
ECONNREFUSED/ETIMEDOUT/fetch failed. Você precisa rotear pelo proxy corporativo → defina HTTPS_PROXY.SSL certificate verification failed/self-signed → coloque a CA corporativa em NODE_EXTRA_CA_CERTS. Nunca desative a verificação.Could not resolve host/ENOTFOUND. DNS fora do ar, VPN com resíduos, ou Docker interceptando o tráfego.
Se curl -I https://api.anthropic.com tiver sucesso, o problema se restringe ao espaço entre o Claude Code e a rede.
2. Configuração de proxy (HTTPS_PROXY)
Quando você precisa rotear por um proxy corporativo, defina as variáveis de ambiente de proxy padrão. O Claude Code as respeita.
# Recomendado: proxy HTTPS
export HTTPS_PROXY=http://proxy.example.com:8080
# Se HTTPS não estiver disponível, HTTP_PROXY
export HTTP_PROXY=http://proxy.example.com:8080
# Destinos que ignoram o proxy (separados por espaço ou vírgula)
export NO_PROXY="localhost,127.0.0.1,.internal.example.com"
# Proxy com autenticação (evite codificar senhas no código)
export HTTPS_PROXY=http://username:password@proxy.example.com:8080Ressalvas: proxies SOCKS não são suportados. Para proxies NTLM / Kerberos, a recomendação oficial é colocar um LLM gateway no meio e apontar ANTHROPIC_BASE_URL para ele. Além disso, se você usa servidores MCP, precisa definir explicitamente HTTPS_PROXY e NODE_EXTRA_CA_CERTS no env de cada servidor (eles não são herdados do processo pai). Essas variáveis também podem ir no bloco env do settings.json.
3. TLS e certificados de CA corporativa (o mais importante, com segurança)
O bloqueio corporativo mais comum é um erro de certificado causado por um proxy de inspeção de TLS (Zscaler, Netskope, Palo Alto, etc.) substituindo os certificados. As mensagens típicas são unable to get local issuer certificate e SELF_SIGNED_CERT_IN_CHAIN.
Para dar contexto, versões recentes do Claude Code confiam TANTO no seu conjunto de CAs embutido QUANTO no repositório de confiança do SO. Então se a CA raiz corporativa estiver no repositório de certificados do SO, muitas vezes funciona sem configuração extra (o comportamento varia por versão, então confirme a mais recente). Se não estiver no repositório do SO, aponte NODE_EXTRA_CA_CERTS para o pacote de CA (PEM) que você recebeu do TI:
# A maneira correta e segura: confiar na CA corporativa
export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem
# Se o proxy exigir um certificado de cliente (mTLS)
export CLAUDE_CODE_CLIENT_CERT=/path/to/client-cert.pem
export CLAUDE_CODE_CLIENT_KEY=/path/to/client-key.pem⚠️ NÃO faça: desativar a verificação de TLS
Desligar a verificação de certificado com NODE_TLS_REJECT_UNAUTHORIZED=0 parece "resolver", mas nunca faça isso. Isso desativa a verificação de TLS para o processo inteiro, então todo o tráfego — inclusive para api.anthropic.com — fica exposto a ataques man-in-the-middle (espionagem/adulteração). Isso arrisca vazar credenciais e código. A resposta correta é sempre "confiar adequadamente na CA corporativa via NODE_EXTRA_CA_CERTS."
Se você se deparar com um erro de certificado na hora da instalação (antes do binário existir), passe a CA para o curl: curl --cacert /path/to/corporate-ca.pem -fsSL https://claude.ai/install.sh | bash.
4. Domínios para liberar no firewall
Se o seu firewall restringe destinos, libere estes domínios sobre HTTPS (443) (conforme os requisitos de rede oficiais).
| Domínio | Usado para |
|---|---|
api.anthropic.com | Requisições da Claude API (obrigatório) |
claude.ai | Autenticação da conta claude.ai |
platform.claude.com | Autenticação da conta do Console |
downloads.claude.ai | Instalador, atualização automática, plugins |
raw.githubusercontent.com | Notas de versão, marketplace |
Telemetria (statsig.anthropic.com) e relatório de erros (*.sentry.io) são opcionais e podem ser desativados (não precisam estar na lista de liberação obrigatória). Se você gerencia as instalações por conta própria via npm, talvez não precise de downloads.claude.ai. Os domínios e faixas de IP exatos podem ser revisados, então confirme os mais recentes na página oficial de configuração de rede.
5. O fluxo de diagnóstico
Quando não conecta, vá de cima para baixo. O primeiro curl define a direção.
Isole de cima para baixo
curl -I https://api.anthropic.com (Windows: curl.exe) para testar a acessibilidade. Se passar, o problema está do seu lado./doctor (ou claude doctor se ele não iniciar) e verifique as variáveis de ambiente do proxy.NODE_EXTRA_CA_CERTS; proxy não definido → aplique HTTPS_PROXY.curl passa mas o Claude Code falha, suspeite de DNS (resolv.conf do WSL), VPN com resíduos ou Docker interceptando o tráfego.
A regra: "teste a acessibilidade (curl) primeiro, depois aplique a configuração da camada que te travou."
Lide com certificados via NODE_EXTRA_CA_CERTS. Nunca desative a verificação.
6. Como diferenciar de erros parecidos
"Travou" também pode não ser de rede. A grande divisão é "chegou ao servidor?"
| Sintoma | O que realmente é | Solução principal |
|---|---|---|
| Unable to connect / fetch failed / erro de certificado | Este artigo = rede (nunca chegou ao servidor) | HTTPS_PROXY / NODE_EXTRA_CA_CERTS / liberação no firewall |
| 401 / 403 / Invalid API key | Autenticação (chegou, mas há um problema de credencial) | erros de autenticação / login |
| 529 / 500 | Lado do servidor (chegou, mas sobrecarregado / erro interno) | erros 529/500 |
| 429 Request rejected | Limite de taxa (chegou, mas tráfego demais) | Reduza o ritmo, aguarde |
Um macete: erros de rede significam "nunca chegou ao servidor" (TCP/TLS/DNS), e HTTPS_PROXY ou NODE_EXTRA_CA_CERTS só ajudam nessa camada. Em contraste, 401/403, 529/500 e 429 são "respostas depois de chegar", então mexer no proxy ou na CA não vai resolvê-los. Se o curl tem sucesso ou não é o melhor indicador para separar os dois casos. Para outros erros comuns, veja a coletânea de erros.
Resumo
Os erros de rede/proxy do Claude Code (Unable to connect / fetch failed / SSL certificate verification failed, etc.) significam que a requisição nunca chegou ao servidor = uma falha de TCP/TLS/DNS. Eles são diferentes de autenticação (401/403), servidor (529/500) e taxa (429), e os culpados habituais são o proxy, a inspeção de TLS e o firewall corporativos.
As soluções: (1) atrás de um proxy, defina HTTPS_PROXY (SOCKS não suportado; NTLM/Kerberos via um gateway), (2) para erros de certificado coloque a CA corporativa em NODE_EXTRA_CA_CERTS — nunca NODE_TLS_REJECT_UNAUTHORIZED=0, (3) libere api.anthropic.com etc. no firewall. Diagnostique primeiro testando a acessibilidade com curl -I https://api.anthropic.com -> /doctor e verificação do proxy -> configurações de certificado/proxy -> uma conexão direta para confirmar -> DNS/VPN/Docker. A chave é separar rede de autenticação/servidor/taxa pela pergunta "chegou ao servidor?" Relacionados: erros de autenticação / login, erros 529/500, coletânea de erros do Claude Code.
FAQ
Q. No PC da minha empresa aparece "Unable to connect to API" e não consigo conectar.
A. Normalmente você precisa rotear por um proxy corporativo que não está configurado. Primeiro verifique a acessibilidade com curl -I https://api.anthropic.com; se falhar, defina um proxy como export HTTPS_PROXY=http://proxy.example.com:8080 (adicione user:password@ para um proxy com autenticação). Observe que SOCKS não é suportado, e para proxies NTLM/Kerberos a recomendação oficial é passar por um LLM gateway.
Q. Aparece "SSL certificate verification failed".
A. Isso normalmente é um proxy corporativo de inspeção de TLS (por exemplo, Zscaler) substituindo os certificados. Obtenha a CA raiz corporativa (PEM) com o TI e defina export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem. Se a CA corporativa já estiver no repositório de certificados do SO, pode funcionar sem configuração. Nunca desative a verificação com NODE_TLS_REJECT_UNAUTHORIZED=0 — isso expõe todo o tráfego à interceptação.
Q. Definir NODE_TLS_REJECT_UNAUTHORIZED=0 resolveu. Isso está OK?
A. Não — reverta agora. Isso desativa a verificação de certificado de TLS para o processo inteiro, deixando todo o tráfego — inclusive para api.anthropic.com — indefeso contra ataques man-in-the-middle (espionagem/adulteração). É um risco de segurança sério que pode vazar credenciais e código-fonte. A única solução correta é confiar adequadamente na CA corporativa via NODE_EXTRA_CA_CERTS.
Q. Quais domínios devo liberar no firewall?
A. Sobre HTTPS (443), no mínimo libere api.anthropic.com (API), claude.ai e platform.claude.com (autenticação), downloads.claude.ai (instalador/atualizações) e raw.githubusercontent.com. Telemetria (statsig) e relatório de erros (sentry) são opcionais. Os domínios/IPs exatos podem ser revisados, então confirme os mais recentes na página oficial de configuração de rede.
Q. O curl funciona, mas só o Claude Code não conecta.
A. A causa muitas vezes está entre o Claude Code e o SO. Casos comuns: um /etc/resolv.conf do WSL apontando para um DNS morto, resíduos de VPN (por exemplo, interfaces utun antigas do macOS), ou uma ferramenta residente como o Docker interceptando o tráfego. Tente uma conexão direta sem VPN, pare as ferramentas residentes e revise o DNS, nessa ordem. Observe que erros 5xx transitórios são repetidos automaticamente até 10 vezes, então se você vir um erro enquanto o curl tem sucesso, as tentativas já foram esgotadas.
