Sommaire
Vous tentez d'utiliser Claude Code sur une machine d'entreprise ou via un VPN, et la connexion échoue avec des erreurs de ce genre ?
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 failedCe sont des erreurs réseau qui signifient « Claude Code ne peut pas atteindre le serveur d'Anthropic (api.anthropic.com). » Il ne s'agit ni d'authentification (401/403), ni de surcharge serveur (529/500), ni d'une limite de débit (429) — la requête n'a tout simplement jamais atteint le serveur. Les causes habituelles sont les proxys d'entreprise, l'inspection TLS (les certificats) et les pare-feux, ce qui rend ce problème particulièrement fréquent sur les réseaux d'entreprise. Cet article couvre la configuration du proxy, les certificats CA d'entreprise, les domaines à autoriser et les étapes de diagnostic — sur la base d'informations officielles.
Les points clés d'emblée. (1) Derrière un proxy, définissez HTTPS_PROXY. (2) Pour une erreur de certificat due à l'inspection TLS (Zscaler, etc.), pointez NODE_EXTRA_CA_CERTS vers le CA d'entreprise — et ne désactivez jamais la vérification avec NODE_TLS_REJECT_UNAUTHORIZED=0 (cela expose tout le trafic à l'interception). (3) Commencez par lancer curl -I https://api.anthropic.com pour vérifier « est-ce que ça atteint même le serveur ? » — c'est le point de départ du triage.
Ça n'atteint jamais le serveur
— l'endroit où ça s'arrête décide du correctif
HTTPS_PROXYNODE_EXTRA_CA_CERTS
Lancez d'abord curl -I https://api.anthropic.com pour vérifier si ça atteint le serveur.
Une fois que vous savez où ça s'arrête (proxy / TLS / pare-feu), le réglage à appliquer est décidé.
1. Ce que cette erreur vous dit vraiment
Unable to connect to API, fetch failed, ECONNREFUSED / ETIMEDOUT signifient « la requête n'a pas atteint le serveur d'Anthropic » = elle a échoué quelque part au niveau TCP/TLS/DNS. C'est la différence décisive avec les autres erreurs : l'authentification (401/403), le serveur (529/500) et le débit (429) sont des réponses obtenues après avoir atteint le serveur, tandis que les erreurs réseau signifient que ça n'est jamais arrivé jusque-là.
Sur les réseaux d'entreprise, les blocages typiques se répartissent en trois couches. (1) Proxy — vous ne pouvez pas sortir directement et devez passer par un proxy d'entreprise qui n'est pas configuré. (2) Inspection TLS (certificats) — un proxy d'inspection comme Zscaler remplace les certificats, vous devez donc faire confiance au CA racine de l'entreprise. (3) Pare-feu — les domaines requis ne sont pas autorisés. La première chose à faire est de confirmer « est-ce que ça atteint le serveur ? » avec curl -I https://api.anthropic.com — cette seule vérification sépare « un problème réseau » de « tout le reste ».
Où ça s'arrête = quel réglage appliquer
ECONNREFUSED/ETIMEDOUT/fetch failed. Vous devez passer par le proxy d'entreprise → définissez HTTPS_PROXY.SSL certificate verification failed/self-signed → placez le CA d'entreprise dans NODE_EXTRA_CA_CERTS. Ne désactivez jamais la vérification.Could not resolve host/ENOTFOUND. DNS hors service, VPN résiduel ou Docker qui intercepte le trafic.
Si curl -I https://api.anthropic.com réussit, le problème se réduit à l'espace entre Claude Code et le réseau.
2. Configuration du proxy (HTTPS_PROXY)
Lorsque vous devez passer par un proxy d'entreprise, définissez les variables d'environnement de proxy standard. Claude Code les respecte.
# Recommandé : proxy HTTPS
export HTTPS_PROXY=http://proxy.example.com:8080
# Si HTTPS n'est pas disponible, HTTP_PROXY
export HTTP_PROXY=http://proxy.example.com:8080
# Destinations qui contournent le proxy (séparées par espace ou virgule)
export NO_PROXY="localhost,127.0.0.1,.internal.example.com"
# Proxy avec authentification (évitez de coder les mots de passe en dur)
export HTTPS_PROXY=http://username:password@proxy.example.com:8080Points d'attention : les proxys SOCKS ne sont pas pris en charge. Pour les proxys NTLM / Kerberos, la recommandation officielle est de mettre en place une passerelle LLM (LLM gateway) entre les deux et de pointer ANTHROPIC_BASE_URL vers elle. De plus, si vous utilisez des serveurs MCP, vous devez définir explicitement HTTPS_PROXY et NODE_EXTRA_CA_CERTS dans le bloc env de chaque serveur (ils ne sont pas hérités du parent). Ces variables peuvent aussi figurer dans le bloc env de settings.json.
3. TLS et certificats CA d'entreprise (le plus important, en toute sécurité)
Le blocage d'entreprise le plus courant est une erreur de certificat causée par un proxy d'inspection TLS (Zscaler, Netskope, Palo Alto, etc.) qui remplace les certificats. Les messages typiques sont unable to get local issuer certificate et SELF_SIGNED_CERT_IN_CHAIN.
Pour le contexte, les versions récentes de Claude Code font confiance À LA FOIS à leur jeu de CA intégré ET au magasin de certificats du système d'exploitation. Ainsi, si le CA racine de l'entreprise se trouve dans le magasin de certificats de l'OS, cela fonctionne souvent sans configuration supplémentaire (le comportement varie selon la version, vérifiez donc la dernière en date). S'il n'est pas dans le magasin de l'OS, pointez NODE_EXTRA_CA_CERTS vers le bundle CA (PEM) que vous avez reçu du service informatique :
# La bonne méthode, sécurisée : faire confiance au CA d'entreprise
export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem
# Si le proxy exige un certificat client (mTLS)
export CLAUDE_CODE_CLIENT_CERT=/path/to/client-cert.pem
export CLAUDE_CODE_CLIENT_KEY=/path/to/client-key.pem⚠️ À NE PAS faire : désactiver la vérification TLS
Désactiver la vérification des certificats avec NODE_TLS_REJECT_UNAUTHORIZED=0 semble « résoudre » le problème, mais ne faites jamais cela. Cela désactive la vérification TLS pour l'ensemble du processus, de sorte que tout le trafic — y compris vers api.anthropic.com — est exposé aux attaques de l'homme du milieu (écoute/altération). Cela risque de divulguer des identifiants et du code. La bonne réponse est toujours de « faire correctement confiance au CA d'entreprise via NODE_EXTRA_CA_CERTS ».
Si vous rencontrez une erreur de certificat au moment de l'installation (avant que le binaire n'existe), transmettez le CA à curl : curl --cacert /path/to/corporate-ca.pem -fsSL https://claude.ai/install.sh | bash.
4. Domaines à autoriser dans le pare-feu
Si votre pare-feu restreint les destinations, autorisez ces domaines via HTTPS (443) (conformément aux exigences réseau officielles).
| Domaine | Utilisé pour |
|---|---|
api.anthropic.com | Requêtes à l'API Claude (requis) |
claude.ai | Authentification du compte claude.ai |
platform.claude.com | Authentification du compte Console |
downloads.claude.ai | Installateur, mises à jour automatiques, plugins |
raw.githubusercontent.com | Notes de version, marketplace |
La télémétrie (statsig.anthropic.com) et le rapport d'erreurs (*.sentry.io) sont facultatifs et peuvent être désactivés (pas besoin de les inclure dans la liste d'autorisation obligatoire). Si vous gérez les installations vous-même via npm, vous n'avez peut-être pas besoin de downloads.claude.ai. Les domaines et plages d'adresses IP exacts peuvent être révisés, alors confirmez les dernières informations sur la page officielle de configuration réseau.
5. Le flux de diagnostic
Quand la connexion échoue, procédez de haut en bas. Le premier curl donne la direction.
Isolez le problème de haut en bas
curl -I https://api.anthropic.com (sous Windows : curl.exe) pour tester l'accessibilité. Si ça passe, le problème est de votre côté./doctor (ou claude doctor si ça ne démarre pas) et vérifiez les variables d'environnement du proxy.NODE_EXTRA_CA_CERTS ; aucun proxy défini → appliquez HTTPS_PROXY.curl passe mais que Claude Code échoue, suspectez le DNS (WSL resolv.conf), un VPN résiduel ou Docker qui intercepte le trafic.
La règle : « testez d'abord l'accessibilité (curl), puis appliquez le réglage de la couche qui vous a bloqué. »
Gérez les certificats avec NODE_EXTRA_CA_CERTS. Ne désactivez jamais la vérification.
6. La distinguer des erreurs similaires
« Ça s'est arrêté » peut aussi être autre chose que du réseau. La grande séparation est « est-ce que ça a atteint le serveur ? »
| Symptôme | Ce que c'est réellement | Correctif principal |
|---|---|---|
| Unable to connect / fetch failed / erreur de certificat | Cet article = réseau (n'a jamais atteint le serveur) | HTTPS_PROXY / NODE_EXTRA_CA_CERTS / autorisation pare-feu |
| 401 / 403 / Invalid API key | Authentification (atteint, mais problème d'identifiant) | erreurs d'authentification / connexion |
| 529 / 500 | Côté serveur (atteint, mais surchargé / erreur interne) | erreurs 529/500 |
| 429 Request rejected | Limite de débit (atteint, mais trop de trafic) | Ralentir, attendre |
Un moyen mnémotechnique : les erreurs réseau signifient « ça n'a jamais atteint le serveur » (TCP/TLS/DNS), et HTTPS_PROXY ou NODE_EXTRA_CA_CERTS n'aident qu'à cette couche. En revanche, 401/403, 529/500 et 429 sont des « réponses obtenues après avoir atteint le serveur », donc ajuster le proxy ou le CA ne les corrigera pas. Le succès ou l'échec de curl est le meilleur indice pour séparer les deux. Pour d'autres erreurs courantes, consultez le récapitulatif des erreurs.
Résumé
Les erreurs réseau/proxy de Claude Code (Unable to connect / fetch failed / SSL certificate verification failed, etc.) signifient que la requête n'a jamais atteint le serveur = un échec TCP/TLS/DNS. Elles sont différentes de l'authentification (401/403), du serveur (529/500) et du débit (429), et les coupables habituels sont le proxy, l'inspection TLS et le pare-feu de l'entreprise.
Les correctifs : (1) derrière un proxy, définissez HTTPS_PROXY (SOCKS non pris en charge ; NTLM/Kerberos via une passerelle), (2) pour les erreurs de certificat, placez le CA d'entreprise dans NODE_EXTRA_CA_CERTS — jamais NODE_TLS_REJECT_UNAUTHORIZED=0, (3) autorisez api.anthropic.com etc. dans le pare-feu. Diagnostiquez en testant d'abord l'accessibilité avec curl -I https://api.anthropic.com -> /doctor et vérification du proxy -> réglages certificat/proxy -> une connexion directe pour confirmer -> DNS/VPN/Docker. L'essentiel est de séparer le réseau de l'authentification/serveur/débit par « est-ce que ça a atteint le serveur ? » En lien : erreurs d'authentification / connexion, erreurs 529/500, récapitulatif des erreurs Claude Code.
FAQ
Q. Sur mon PC d'entreprise, j'obtiens « Unable to connect to API » et je ne peux pas me connecter.
A. En général, vous devez passer par un proxy d'entreprise qui n'est pas configuré. Vérifiez d'abord l'accessibilité avec curl -I https://api.anthropic.com ; si ça échoue, définissez un proxy comme export HTTPS_PROXY=http://proxy.example.com:8080 (ajoutez user:password@ pour un proxy avec authentification). Notez que SOCKS n'est pas pris en charge, et pour les proxys NTLM/Kerberos, la recommandation officielle est de passer par une passerelle LLM.
Q. J'obtiens « SSL certificate verification failed ».
A. Il s'agit généralement d'un proxy d'inspection TLS d'entreprise (par ex. Zscaler) qui remplace les certificats. Obtenez le CA racine de l'entreprise (PEM) auprès du service informatique et définissez export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem. Si le CA d'entreprise est déjà dans le magasin de certificats de l'OS, cela peut fonctionner sans configuration. Ne désactivez jamais la vérification avec NODE_TLS_REJECT_UNAUTHORIZED=0 — cela expose tout le trafic à l'interception.
Q. Définir NODE_TLS_REJECT_UNAUTHORIZED=0 a résolu le problème. Est-ce acceptable ?
A. Non — annulez-le immédiatement. Cela désactive la vérification des certificats TLS pour l'ensemble du processus, laissant tout le trafic — y compris vers api.anthropic.com — sans défense face aux attaques de l'homme du milieu (écoute/altération). C'est un grave risque de sécurité qui peut divulguer des identifiants et du code source. Le seul correctif correct est de faire correctement confiance au CA d'entreprise via NODE_EXTRA_CA_CERTS.
Q. Quels domaines dois-je autoriser dans le pare-feu ?
A. Via HTTPS (443), autorisez au minimum api.anthropic.com (API), claude.ai et platform.claude.com (authentification), downloads.claude.ai (installateur/mises à jour) et raw.githubusercontent.com. La télémétrie (statsig) et le rapport d'erreurs (sentry) sont facultatifs. Les domaines/IP exacts peuvent être révisés, alors confirmez les dernières informations sur la page officielle de configuration réseau.
Q. curl fonctionne, mais seul Claude Code ne se connecte pas.
A. La cause se situe souvent entre Claude Code et l'OS. Cas courants : un /etc/resolv.conf de WSL qui pointe vers un DNS hors service, des résidus de VPN (par ex. d'anciennes interfaces utun sous macOS), ou un outil résident comme Docker qui intercepte le trafic. Essayez une connexion directe hors VPN, arrêtez les outils résidents et passez en revue le DNS, dans cet ordre. Notez que les erreurs 5xx transitoires font l'objet de jusqu'à 10 nouvelles tentatives automatiques ; donc si vous voyez une erreur alors que curl réussit, les nouvelles tentatives sont déjà épuisées.
