Diagnostic des erreurs de proxy : 407, 502, 504 et tunnel connection failed — guide étape par étape

Les erreurs de proxy font peur par leur soudaineté. L'instant d'avant, la requête fonctionnait, et maintenant vous voyez un mystérieux 407, 502 ou un message tunnel connection failed. Bonne nouvelle : derrière chaque erreur se cache une cause claire et logique. Ce guide va vous apprendre à lire ces messages comme un livre ouvert.

Introduction : pourquoi ce guide et ce que vous allez y gagner

Travailler avec un proxy, c'est comme une conversation téléphonique via un interprète. Votre client parle au proxy, le proxy parle au site cible, et la réponse revient par le même chemin. Quand quelque chose casse, il faut comprendre à quel maillon précis le problème est apparu. C'est exactement l'objet de ce guide.

Ce que vous allez obtenir :

• La capacité de distinguer instantanément une erreur de proxy d'une erreur de site cible.
• La compréhension de ce que signifient les codes 407, 502, 504, 403 et le message tunnel connection failed.
• La compétence de lire la sortie de la commande curl -v ligne par ligne, avec une séparation nette des segments client-proxy-serveur.
• Des exemples prêts à l'emploi de diagnostic en curl, Python requests et Node.js avec de vrais messages d'erreur.
• Un tableau de diagnostic rapide symptôme-cause-vérification, à imprimer et garder sous la main.

À qui s'adresse ce guide. Il est écrit pour ceux qui débutent avec les proxies, mais il contient aussi des détails avancés pour les développeurs expérimentés et les spécialistes de l'automatisation. Si vous configurez des scrapers, faites du multi-compte ou voulez simplement comprendre pourquoi votre script a soudain arrêté de récupérer des données, ce contenu est pour vous.

Ce qu'il faut savoir au préalable. Une compréhension de base de ce qu'est une URL, un port et une requête HTTP suffit. Aucune connaissance réseau approfondie n'est requise. Nous expliquerons tous les termes simplement au fil du texte.

Combien de temps cela prendra. Une première lecture prendra environ 30 à 40 minutes. La mise en pratique sur votre projet prendra encore 20 à 30 minutes. Ensuite, diagnostiquer une erreur typique vous prendra une à deux minutes.

Précision importante sur le sujet. Dans ce guide, nous traitons uniquement les erreurs de la couche proxy elle-même. Le code 429 (trop de requêtes) et les stratégies de retry ne sont pas abordés ici, car c'est un vaste sujet à part entière avec sa propre logique et ses approches. Le 429 mérite un article dédié aux retries et aux limites. Ici, nous nous concentrons strictement sur le diagnostic des défaillances de connexion proxy.

Préparation : outils et accès

Avant de commencer le diagnostic, rassemblons une boîte à outils. Tous ces outils sont gratuits et fonctionnent sur n'importe quel système d'exploitation.

Outils nécessaires

1. Installez curl. Sur la plupart des systèmes Linux et macOS, il est déjà présent. Vérifiez avec la commande curl --version. Si vous voyez un numéro de version, tout est prêt.
2. Sous Windows, curl fait partie du système depuis les versions modernes. Ouvrez PowerShell et tapez la même commande de vérification.
3. Installez Python version 3.10 ou plus récent si vous prévoyez les exemples avec requests. Vérifiez avec python --version.
4. Installez la bibliothèque requests avec pip install requests dans le terminal.
5. Installez Node.js version 20 ou plus récent pour les exemples JavaScript. Vérifiez avec node --version.

Ce qu'il faut préparer

• Les données de votre proxy : adresse de l'hôte, port, identifiant et mot de passe si nécessaire.
• Une adresse cible de test à laquelle vous vous adresserez. Pour les vérifications, il est pratique d'utiliser un site simple qui renvoie des informations sur la requête.
• Un éditeur de texte pour sauvegarder les logs et les notes de diagnostic.

Conseil : Créez un fichier texte séparé nommé diagnostic-notes. Notez-y chaque commande et son résultat. Cela vous sauvera quand, une demi-heure plus tard, vous aurez oublié ce que vous avez déjà testé.

⚠️ Attention : Ne sauvegardez jamais l'identifiant et le mot de passe de votre proxy dans des chats publics, des dépôts publics ou des captures d'écran. Une fuite de ces données donne à des tiers l'accès à votre trafic. Conservez-les dans un gestionnaire de mots de passe sécurisé.

✅ Vérification : À ce stade, vous devez réussir à exécuter les trois commandes de vérification de version : curl, python et node. Si l'une ne fonctionne pas, revenez à l'installation de l'outil concerné.

Notions de base expliquées simplement

Pour que le diagnostic soit conscient, passons en revue quelques termes clés. Ne sautez pas cette section, même si les termes vous semblent familiers.

Ce qu'est vraiment un proxy

Un proxy est un intermédiaire entre votre programme et le site cible. Votre requête arrive d'abord au proxy, puis le proxy la transmet plus loin. La réponse revient par le même chemin. À cause de cet intermédiaire, toute erreur peut survenir à trois endroits : chez votre client, chez le proxy lui-même ou chez le site cible.

La distinction fondamentale : client, proxy, serveur

Mémorisez les trois maillons de la chaîne. Premier maillon : votre client, c'est-à-dire le programme qui envoie la requête. Deuxième maillon : le proxy, l'intermédiaire. Troisième maillon : le serveur cible, le site où vous voulez aller. Tout le diagnostic se résume à une question : à quel des trois maillons la défaillance est-elle survenue ?

Les codes HTTP en deux mots

Les sites et les proxies répondent avec des codes numériques. Les codes en 4 (par exemple 407, 403) signifient généralement un problème du côté de la requête ou de l'accès. Les codes en 5 (502, 504) signifient un problème du côté du serveur ou de l'intermédiaire. Mais il y a une subtilité sournoise : le code 502 peut être envoyé aussi bien par le site cible que par le proxy lui-même. Apprendre à les distinguer est l'un des objectifs principaux du guide.

Différence entre HTTP et HTTPS via un proxy

Quand vous allez sur un site classique en HTTP, le proxy voit toute la requête. Quand vous allez sur un site sécurisé en HTTPS, le proxy ne peut pas lire le contenu. À la place, le client demande au proxy de créer un tunnel sécurisé via une commande spéciale appelée CONNECT. C'est pourquoi l'erreur tunnel connection failed n'apparaît qu'en HTTPS. Nous détaillerons cela séparément.

Conseil : Gardez en tête une image simple. Le client frappe à la porte du proxy. Le proxy décide de le laisser passer. Puis le proxy frappe à la porte du site. Le site décide de répondre. L'erreur surgit à l'endroit où le coup n'a pas abouti.

Étape 1 : Comment distinguer une erreur de proxy d'une erreur de site cible

Objectif de l'étape : apprendre en quelques secondes à savoir qui est en cause — le proxy ou le site. C'est la compétence fondamentale par laquelle commence tout diagnostic.

Le principe fondamental de distinction

La question clé est la suivante : votre requête a-t-elle atteint le site cible ou est-elle restée bloquée au proxy ? Si la requête est restée bloquée au proxy, c'est la couche proxy qui est en cause. Si la requête a atteint le site et que le site a répondu, le problème vient du site.

1. Regardez le code d'erreur et le texte du message.
2. Déterminez qui a envoyé cette réponse : le proxy ou le serveur. L'en-tête de réponse et le contenu vous le diront.
3. Si le texte de l'erreur mentionne directement le mot proxy, tunnel ou le nom d'un logiciel proxy, c'est presque certainement la couche proxy qui est en cause.
4. Si la réponse contient une page HTML habituelle du site cible avec son logo et son design, alors la requête a atteint le site.

Trois signes rapides d'une erreur propre au proxy

• Code 407. Ce code n'existe que chez le proxy. Le site cible ne l'envoie jamais. Vous voyez 407 — vous êtes donc bien sur la couche proxy.
• Texte tunnel connection failed ou Received HTTP code provenant du proxy. Ces formulations sont générées par l'intermédiaire lui-même.
• Refus instantané de connexion. Si la requête échoue presque immédiatement, avant même d'avoir pu atteindre le site, le problème se situe probablement entre le client et le proxy.

Conseil : Faites une expérience de contrôle. Faites la même requête directement, sans proxy. Si en direct tout fonctionne et que via le proxy non, le problème vient de la couche proxy ou de son interaction avec le site. Cela élimine la moitié des hypothèses en une minute.

Exemple en curl pour une vérification rapide

Exécutez une requête via le proxy avec le drapeau de sortie détaillée. La commande ressemble à ceci : curl -v -x http://identifiant:motdepasse@hôte:port https://site-exemple. Le drapeau -v affiche tout le dialogue. Le drapeau -x définit le proxy. Regardez les lignes commençant par des flèches et des astérisques. Nous les détaillerons dans une étape dédiée à la lecture des logs.

⚠️ Attention : Ne tirez jamais de conclusion d'une seule requête vers un site instable. Répétez la requête deux ou trois fois. Une panne réseau ponctuelle peut ressembler à une erreur de proxy, alors que le proxy n'y est pour rien.

✅ Vérification : Vous devez pouvoir répondre, pour n'importe quel message d'erreur, à la question : est-ce le proxy ou le site qui l'a envoyé ? Si oui, passez à la suite. Si vous hésitez encore, revenez aux trois signes rapides ci-dessus.

Étape 2 : L'erreur 407 Proxy Authentication Required

Objectif de l'étape : apprendre à corriger l'erreur d'authentification la plus fréquente sur un proxy et comprendre en quoi elle diffère du code 401 qui lui ressemble.

Ce que signifie 407 et en quoi il diffère de 401

Le code 407 dit littéralement : le proxy exige que vous vous présentiez avec un identifiant et un mot de passe, mais vous ne l'avez pas fait ou vous l'avez mal fait. La différence clé avec 401 : le code 401 est envoyé par le site cible quand c'est lui qui exige l'authentification. Le code 407, lui, est envoyé par le proxy. Si vous voyez 407, c'est que vous n'avez même pas atteint le site — l'intermédiaire vous a arrêté à l'entrée.

Où exactement se perdent l'identifiant et le mot de passe

Le plus souvent, les données se perdent à trois endroits.

1. L'identifiant et le mot de passe ne sont pas transmis du tout dans la commande. Le client a frappé à la porte du proxy en anonyme, et le proxy l'a refoulé.
2. Les données sont transmises, mais avec une faute de frappe. Un espace en trop ou un mauvais clavier — et l'authentification échoue.
3. Les données sont transmises correctement, mais le mot de passe contient des caractères spéciaux qui cassent la structure de la chaîne de connexion. C'est la cause la plus sournoise.

Caractères spéciaux dans le mot de passe et encodage URL

La chaîne de connexion au proxy ressemble à ceci : identifiant deux-points motdepasse arobase hôte deux-points port. Le problème, c'est que le deux-points, l'arobase, le slash et d'autres caractères ont une signification spéciale dans cette chaîne. Si votre mot de passe contient, par exemple, une arobase ou un deux-points, le programme le comprendra mal et cassera la chaîne au mauvais endroit.

La solution s'appelle l'encodage URL. Les caractères spéciaux sont remplacés par un code composé du signe pourcent et de deux chiffres ou lettres. Par exemple, l'arobase devient pourcent quarante, le deux-points devient pourcent trois A, le slash devient pourcent deux F, l'espace devient pourcent vingt.

1. Trouvez tous les caractères spéciaux dans votre mot de passe.
2. Remplacez chacun par son code URL.
3. Reconstituez la chaîne de connexion avec le mot de passe encodé.
4. Répétez la requête.

Conseil : N'encodez pas le mot de passe à la main s'il est complexe. En Python, il existe une fonction d'encodage du module urllib.parse appelée quote. Passez-lui le mot de passe et elle renverra une version sûre. Cela élimine les erreurs de saisie manuelle.

Exemple en curl

Le vrai texte d'erreur en cas d'authentification incorrecte ressemble à ceci : curl (56) Received HTTP code 407 from proxy after CONNECT. Ou, sur un site HTTP : HTTP 407 Proxy Authentication Required. La bonne commande avec authentification : curl -v --proxy-user identifiant:motdepasse -x http://hôte:port https://site-exemple. Utiliser le drapeau --proxy-user est souvent plus fiable que d'inscrire les données directement dans l'adresse, car curl gérera correctement les caractères.

Exemple en Python requests

Dans requests, le proxy se définit via un dictionnaire. Les clés http et https, les valeurs sont des chaînes de connexion. Si le mot de passe contient des caractères spéciaux, enveloppez-le dans la fonction quote. Erreur typique dans l'objet de réponse : response.status_code renverra 407, et le texte mentionnera Proxy Authentication Required. Vérifiez bien le code de statut, pas seulement le texte.

Exemple en Node.js

Dans Node, avec les clients populaires, le proxy se définit via un agent spécial. La vraie erreur ressemble à un objet avec un champ statusCode égal à 407 ou à une promesse rejetée avec un message d'erreur d'authentification du tunnel. Assurez-vous de transmettre l'en-tête d'autorisation du proxy, pas l'en-tête d'autorisation du site — ce sont deux choses différentes.

⚠️ Attention : L'en-tête d'autorisation pour le proxy et l'en-tête d'autorisation pour le site sont deux en-têtes différents. L'un s'appelle Proxy-Authorization, l'autre Authorization. Si vous les confondez, vous obtiendrez soit 407 du proxy, soit 401 du site. Vérifiez quel en-tête votre bibliothèque envoie.

✅ Vérification : Après correction de l'authentification, le code de réponse doit passer de 407 à autre chose. Même si le site répond avec sa propre erreur, c'est déjà un progrès : vous avez franchi le proxy et atteint le site.

Étape 3 : L'erreur 502 venant du proxy

Objectif de l'étape : apprendre à comprendre quand un 502 signifie un problème du site cible et quand il s'agit d'une défaillance du canal proxy lui-même.

Ce que signifie 502

Le code 502 s'appelle Bad Gateway, c'est-à-dire mauvaise passerelle. Il dit que l'intermédiaire a tenté de s'adresser au maillon suivant, mais a reçu une réponse confuse ou interrompue. Le problème, c'est que le 502 peut arriver dans deux situations totalement différentes, et qu'elles se ressemblent extérieurement.

Quand l'hôte cible est en cause

Première situation : le proxy s'est bien connecté au site cible, mais le site a renvoyé du charabia, coupé la connexion ou n'a pas pu lui-même obtenir de réponse de son backend. Dans ce cas, le proxy vous a honnêtement transmis le 502 comme un constat : j'ai atteint le site, mais le site a mal répondu.

1. Faites la même requête directement, sans proxy.
2. Si en direct le site répond aussi 502 ou se bloque, c'est le site qui est en cause, pas le proxy.
3. Dans ce cas, changer de proxy ne sert à rien. Le problème est du côté de la cible.

Quand le canal lui-même est en cause

Deuxième situation : le proxy lui-même est instable, son canal en amont s'est rompu, ou le proxy n'a même pas pu établir correctement la connexion avec le site. Alors le 502 est le signe d'un intermédiaire malade.

1. Faites une requête via le même proxy vers un site réputé stable.
2. Si même un site stable renvoie 502, le problème vient du canal proxy.
3. Essayez un autre proxy ou un autre nœud, si vous en avez un.

Conseil : La méthode de vérification croisée fonctionne infailliblement. Changez une seule variable à la fois. D'abord fixez le proxy et changez le site. Ensuite fixez le site et changez le proxy. L'intersection des résultats désignera le coupable.

De vrais textes d'erreur

En curl, vous verrez une réponse HTTP avec le code 502 et souvent une page HTML portant la mention Bad Gateway. Parfois, dans les en-têtes de réponse, on voit un indice sur le serveur qui a envoyé la réponse. En Python requests, c'est response.status_code égal à 502. En Node, c'est le champ statusCode égal à 502. Faites attention au corps de la réponse : une page soignée du site cible indique que la requête a atteint le site, tandis qu'une page technique concise provient souvent du proxy.

⚠️ Attention : Ne vous empressez pas d'accuser le proxy au premier 502. Les sites cibles renvoient très souvent des 502, surtout sous charge. Faites toujours une requête de contrôle en direct avant de modifier la configuration du proxy.

✅ Vérification : Vous devez pouvoir dire avec assurance, d'après les résultats de deux requêtes croisées : ce 502 vient du site ou du proxy. Si vous n'y arrivez pas encore, répétez les deux requêtes de contrôle et comparez les résultats.

Étape 4 : L'erreur 504 et les timeouts

Objectif de l'étape : apprendre à distinguer deux types de timeouts radicalement différents et à les configurer correctement dans le client.

Ce que signifie 504

Le code 504 s'appelle Gateway Timeout, c'est-à-dire que la passerelle n'a pas attendu la réponse. Il dit que l'intermédiaire a attendu trop longtemps une réponse du maillon suivant et a abandonné. Mais pour comprendre où exactement le temps s'est bloqué, il faut séparer deux types de timeouts.

Connect timeout contre read timeout

Il y a deux moments d'attente totalement différents.

• Connect timeout — c'est le temps d'établissement de la connexion elle-même. Le client essaie de joindre le proxy, ou le proxy essaie de joindre le site. Si la connexion ne s'établit pas dans le temps imparti, le connect timeout se déclenche. C'est généralement le signe que l'adresse est inaccessible ou que le port est fermé.
• Read timeout — c'est le temps d'attente de la réponse une fois la connexion établie. La connexion existe, la requête est partie, mais les données n'arrivent pas. C'est généralement le signe que le site réfléchit longtemps ou est bloqué en cours de traitement.

Comment les séparer dans le client

Un bon diagnostic commence par une configuration séparée de ces deux timeouts. Vous comprendrez alors immédiatement à quelle étape le temps s'est bloqué.

1. En curl, utilisez le drapeau --connect-timeout pour limiter le temps d'établissement de la connexion. Séparément, le drapeau --max-time limite le temps total de toute l'opération.
2. En Python requests, le paramètre timeout peut être passé sous forme d'un tuple de deux nombres. Le premier nombre est le connect timeout, le second le read timeout. Par exemple, un timeout de cinq et trente secondes.
3. En Node, la plupart des clients ont des réglages séparés pour le temps de connexion et le temps d'attente de la réponse. Donnez-leur des valeurs différentes pour voir lequel s'est déclenché.

Comment lire le résultat

Si le connect timeout s'est déclenché, c'est que vous n'avez même pas établi la connexion. Vérifiez l'accessibilité du proxy et l'exactitude du port. Si le read timeout s'est déclenché, la connexion existait, mais la réponse n'est pas arrivée à temps. Vérifiez si le site n'est pas surchargé et si votre requête n'est pas trop lourde.

Conseil : Réglez le connect timeout petit, environ cinq secondes. L'établissement d'une connexion se fait soit rapidement, soit pas du tout. Et réglez le read timeout avec de la marge, car certaines pages préparent honnêtement leur réponse plus longtemps.

⚠️ Attention : Un read timeout trop petit provoque de fausses erreurs. Vous couperez des réponses normales mais lentes et penserez que le proxy est cassé. Vérifiez toujours que vous n'avez pas vous-même fixé une limite trop stricte.

De vrais textes d'erreur

En curl, le connect timeout ressemble à un message Connection timed out sur stderr. En Python requests, c'est l'exception ConnectTimeout pour la connexion et ReadTimeout pour la réponse. Le nom même de l'exception vous dit immédiatement quelle étape a échoué. En Node, vous verrez une erreur avec le code ETIMEDOUT ou un message séparé de dépassement du temps de réponse.

✅ Vérification : Après avoir configuré des timeouts séparés, vous devez obtenir dans l'erreur une indication claire : c'est un timeout de connexion ou un timeout de lecture. Si vous ne voyez qu'un mot timeout général sans précision, les timeouts ne sont pas encore séparés.

Étape 5 : L'erreur tunnel connection failed et la méthode CONNECT

Objectif de l'étape : comprendre pourquoi cette erreur n'apparaît que sur les sites sécurisés et comment la diagnostiquer.

Pourquoi l'erreur ne survient qu'en HTTPS

Quand vous allez sur un site HTTP classique, le proxy se contente de transmettre votre requête. Mais quand vous allez sur un site HTTPS, le contenu est chiffré et le proxy ne peut pas le lire. C'est pourquoi le client envoie d'abord au proxy une commande spéciale CONNECT avec l'adresse du site. Cette commande signifie une demande : construis-moi un tunnel sécurisé vers cette adresse, je communiquerai avec le site directement à travers toi.

Si le proxy, pour une raison quelconque, n'a pas pu construire le tunnel, il renvoie l'erreur tunnel connection failed. En HTTP classique, cette commande n'existe pas, donc cette erreur n'arrive pas en HTTP. C'est votre principal signe distinctif.

Les principales causes d'échec du tunnel

• Le proxy n'a pas pu se connecter à l'adresse cible. Le site est peut-être inaccessible ou le port fermé.
• Le proxy interdit la méthode CONNECT vers cette adresse ou ce port. Certains proxies n'autorisent que certains ports.
• L'authentification a échoué. Dans ce cas, vous voyez souvent une combinaison : d'abord une tentative CONNECT, puis le code 407.
• Le proxy est surchargé ou son canal en amont s'est rompu au moment de construire le tunnel.

Comment diagnostiquer

1. Exécutez curl -v vers une adresse HTTPS et trouvez dans la sortie la ligne avec CONNECT. Elle montre le moment de la demande de tunnel.
2. Regardez quelle réponse est arrivée au CONNECT. Une réponse avec le code 200 signifie que le tunnel est construit. Tout autre code signifie un échec.
3. Si vous voyez 407 juste à côté, le problème est l'authentification, pas le tunnel lui-même. Revenez à l'étape sur le 407.
4. Si vous voyez un refus de connexion, le proxy n'a pas pu joindre le site.

Conseil : Vérifiez que vous vous adressez bien à un port autorisé. Les ports classiques pour les connexions sécurisées sont généralement autorisés, tandis que les ports non standard sont bloqués par beaucoup de proxies. Changer le port pour un port standard résout souvent le problème instantanément.

De vrais textes d'erreur

En curl, c'est un message du type curl (56) Received HTTP code from proxy after CONNECT ou directement tunnel connection failed. En Python requests, c'est l'exception ProxyError avec un message imbriqué sur un tunnel échoué. En Node, c'est une erreur indiquant que la connexion tunnel n'a pas pu être établie, souvent avec le code de statut renvoyé par le proxy.

⚠️ Attention : Ne confondez pas un échec de tunnel avec une erreur de certificat. Si le tunnel est construit mais qu'ensuite il y a une plainte sur le certificat sécurisé du site — c'est un autre problème, sans lien avec la couche proxy. Regardez à quelle étape exactement l'erreur est apparue : avant la réponse au CONNECT ou après.

✅ Vérification : Vous devez trouver dans la sortie curl la ligne avec la réponse au CONNECT et comprendre, d'après son code, si le tunnel s'est construit ou non. Réponse 200 — le tunnel existe. Un autre code — cherchez la cause de l'échec.

Étape 6 : L'erreur 403 venant du proxy

Objectif de l'étape : apprendre à reconnaître quand un 403 est envoyé par le proxy à cause de limites, de géographie ou d'un port interdit.

Ce que signifie 403 dans le contexte d'un proxy

Le code 403 s'appelle Forbidden, c'est-à-dire interdit. Généralement, ce code est envoyé par le site cible quand il ferme l'accès. Mais le proxy peut aussi envoyer un 403 quand il décide lui-même de ne pas laisser passer votre requête. La tâche consiste à comprendre qui a posé l'interdiction.

Trois causes de 403 venant du proxy

• Les limites. Le proxy peut limiter le nombre de requêtes, le volume de trafic ou le nombre de connexions simultanées. En cas de dépassement, il renvoie 403 comme refus de service.
• La restriction géographique. Certains proxies n'autorisent l'accès qu'à certaines régions ou, au contraire, interdisent certaines directions. Une requête vers une direction fermée reçoit un 403.
• Le port interdit. Le proxy peut n'autoriser que les ports standards. Une requête vers un port non standard se solde par un refus.

Comment distinguer un 403 du proxy d'un 403 du site

1. Regardez le corps de la réponse. Une page soignée du site cible avec son design signifie que l'interdiction vient du site.
2. Une page technique concise ou une mention du proxy dans le texte signifie que l'interdiction vient de l'intermédiaire.
3. Faites la même requête directement. Si en direct le site renvoie 403 et que via le proxy aussi, c'est le site qui est en cause.
4. Si en direct le site s'ouvre et que via le proxy il renvoie 403, cherchez la cause dans les limites ou restrictions du proxy.

Conseil : Consultez la documentation ou le panneau de contrôle de votre proxy pour connaître les limites. Souvent, dans l'espace client, on voit si le trafic est épuisé ou si la limite de requêtes est atteinte. C'est le moyen le plus rapide de confirmer la cause.

⚠️ Attention : N'essayez pas de contourner les limites du proxy par des astuces. Si vous avez atteint la limite de votre forfait, la bonne solution est d'élargir le forfait ou d'optimiser le nombre de requêtes. Contourner les limitations techniques du service viole les conditions d'utilisation.

De vrais textes d'erreur

En curl, c'est une réponse HTTP 403 Forbidden avec un corps qui indique la source. En Python requests, c'est response.status_code égal à 403. En Node, c'est statusCode égal à 403. Analysez toujours le corps de la réponse avec le code, car c'est le corps qui révèle le véritable auteur de l'interdiction.

✅ Vérification : Vous devez pouvoir déterminer, d'après le corps de la réponse et le résultat de la requête directe, qui a envoyé le 403. Si c'est le proxy — vérifiez les limites, la géo et le port. Si c'est le site — la cause n'est pas dans la couche proxy.

Étape 7 : Rupture de connexion sans réponse — connection reset et EOF

Objectif de l'étape : apprendre à diagnostiquer les cas les plus mystérieux, quand il n'y a aucune réponse et que la connexion se coupe simplement.

Ce que sont ces erreurs

Parfois, vous ne recevez aucun code HTTP. À la place, la connexion se rompt soudainement. Il y a deux manifestations typiques.

• Connection reset. Littéralement — connexion réinitialisée. L'une des parties a fermé brutalement le canal, sans terminer l'échange. Comme si l'interlocuteur raccrochait au milieu d'une phrase.
• EOF, unexpected end of file. Littéralement — fin de données inattendue. Le client attendait la suite de la réponse, mais le flux de données s'est terminé brusquement.

Ce qu'il faut regarder en premier

1. Déterminez le moment de la rupture. Est-elle survenue avant la réponse au CONNECT, pendant l'envoi de la requête ou pendant la réception de la réponse ? La sortie de curl -v montrera la dernière ligne réussie avant la rupture.
2. Si la rupture a eu lieu tout au début, à la connexion au proxy, le problème vient probablement du proxy lui-même ou du chemin réseau jusqu'à lui.
3. Si la rupture a eu lieu après l'établissement du tunnel, pendant l'échange avec le site, le problème vient plus probablement du site ou d'un canal instable.
4. Répétez la requête plusieurs fois. Une rupture qui se répète systématiquement indique une cause systémique. Une rupture aléatoire indique une instabilité réseau temporaire.

Causes fréquentes

• Le proxy est surchargé et ferme de force les connexions en trop.
• Le canal en amont du proxy est instable et se rompt.
• Le site cible ferme la connexion à cause de ses propres limites.
• Problèmes réseau entre les maillons de la chaîne.

Conseil : En cas de ruptures aléatoires, tenez des statistiques. Faites par exemple vingt requêtes d'affilée et comptez combien ont été rompues. Si une sur vingt est rompue, c'est une instabilité tolérable. Si la moitié l'est, il y a un problème systémique à résoudre.

De vrais textes d'erreur

En curl, c'est Connection reset by peer ou Empty reply from server. En Python requests, c'est l'exception ConnectionError avec un message imbriqué sur la réinitialisation de la connexion. En Node, c'est une erreur avec le code ECONNRESET. Ces messages ne contiennent pas de code HTTP précisément parce que l'échange HTTP ne s'est pas terminé normalement.

⚠️ Attention : Une rupture sans réponse se confond facilement avec un timeout. La différence : dans un timeout, le client met fin lui-même à l'attente, tandis que dans un reset, l'autre partie ferme activement le canal. Regardez le texte de l'erreur : le mot reset indique une fermeture active, le mot timeout indique une expiration de l'attente.

✅ Vérification : Vous devez pouvoir déterminer, d'après la dernière ligne de la sortie curl, à quelle étape la connexion s'est rompue. Cela réduit immédiatement le cercle des suspects à un ou deux maillons.

Étape 8 : Pratique — lisons curl -v ligne par ligne

Objectif de l'étape : apprendre à voir dans la sortie curl la frontière entre le client, le proxy et le serveur. C'est le couronnement de tout le guide.

Ce que signifient les symboles en début de ligne

La sortie de curl -v utilise des symboles spéciaux au début de chaque ligne, et c'est votre principale clé de compréhension.

• Une astérisque en début de ligne indique un message d'information de curl lui-même. Ce sont les commentaires du client sur ce qu'il fait : établir la connexion, construire le tunnel, vérifier le certificat.
• Une flèche vers la droite indique les données que le client envoie au proxy ou au serveur. C'est la requête sortante.
• Une flèche vers la gauche indique les données que le client reçoit en réponse. C'est la réponse entrante.

Où passe la frontière client-proxy-serveur

Décomposons le chemin typique vers un site sécurisé via un proxy. D'abord, curl signale par une astérisque qu'il se connecte au proxy à l'adresse et au port indiqués. C'est le segment client-proxy. Ensuite vient une flèche sortante avec la commande CONNECT — le client demande au proxy de construire un tunnel. Puis une flèche entrante avec la réponse au CONNECT — c'est la réponse du proxy. Si le code est 200, le tunnel est construit et la frontière se déplace : tout l'échange se fait désormais client-serveur via le tunnel.

Analyse d'un log réel

Imaginons que vous voyez la séquence suivante. Une ligne avec astérisque : je me connecte à l'adresse et au port du proxy. Cela signifie que le client a trouvé le proxy. La ligne suivante avec astérisque : connexion au proxy établie. Parfait, premier segment franchi. Ensuite une flèche sortante : CONNECT vers l'adresse du site cible. Le client a demandé le tunnel. Puis une flèche entrante : réponse au CONNECT avec un code. C'est ici la bifurcation clé.

1. Si le code de réponse au CONNECT est 200, le tunnel est construit. Lisons la suite.
2. Si le code est 407, le proxy exige l'authentification. Le problème est sur la couche proxy, segment client-proxy. Allez à l'étape sur le 407.
3. Si la ligne indique tunnel connection failed, le proxy n'a pas pu construire le tunnel. La cause est entre le proxy et le site.

Supposons que le tunnel soit construit. Ensuite viennent des astérisques sur la vérification de la connexion sécurisée avec le site. C'est désormais le segment client-serveur. Puis une flèche sortante avec la vraie requête : la ligne de requête et les en-têtes. Notez bien : jusqu'à ce moment, le site n'a même pas vu votre requête, il était occupé à construire le tunnel. Et enfin une flèche entrante avec le code de réponse du site. C'est ici que commence la zone de responsabilité du site cible.

Comment l'appliquer au diagnostic

1. Trouvez la ligne d'établissement de la connexion avec le proxy. Si elle est absente ou en erreur, le problème est entre le client et le proxy.
2. Trouvez la réponse au CONNECT. D'après son code, déterminez si la couche proxy a été franchie.
3. Trouvez la flèche entrante avec la réponse du site. Si elle est là, vous avez atteint le site, et toute erreur ici relève déjà du site.
4. La dernière ligne avant la rupture indique toujours à quel segment tout a cassé.

Conseil : Lisez la sortie de haut en bas comme la chronique du voyage d'une requête. Chaque ligne est une étape du chemin. Dès que vous arrivez à une ligne d'erreur ou de rupture, regardez la ligne réussie précédente. Elle indiquera le dernier maillon vivant.

⚠️ Attention : Le drapeau -v affiche les en-têtes, y compris la ligne d'autorisation du proxy. Si vous partagez le log avec quelqu'un pour obtenir de l'aide, masquez impérativement la ligne avec les données d'autorisation. Sinon, vous révélerez votre identifiant et votre mot de passe.

✅ Vérification : Prenez n'importe lequel de vos logs curl -v et annotez-le : où est le segment client-proxy, où est la réponse au CONNECT, où commence la zone du site. Si vous tracez ces frontières avec assurance, vous avez maîtrisé la compétence clé du diagnostic.

Étape 9 : Tableau de diagnostic rapide symptôme-cause-vérification

Objectif de l'étape : obtenir un aide-mémoire prêt à l'emploi, à consulter au moment de n'importe quelle erreur.

Comment utiliser le tableau

Trouvez votre symptôme dans la première colonne. Lisez la cause probable. Exécutez d'abord l'action de la troisième colonne — c'est elle qui confirmera ou infirmera le plus probablement la cause.

Symptôme : code 407

Cause probable : données d'authentification du proxy non transmises ou incorrectes, ou caractères spéciaux dans le mot de passe ayant cassé la chaîne de connexion. À vérifier en premier : l'exactitude de l'identifiant et du mot de passe, ainsi que l'encodage URL des caractères spéciaux dans le mot de passe.

Symptôme : tunnel connection failed en HTTPS

Cause probable : le proxy n'a pas pu construire le tunnel vers le site, peut-être à cause d'un port interdit ou de l'inaccessibilité du site. À vérifier en premier : la réponse au CONNECT dans la sortie de curl -v et l'autorisation du port cible.

Symptôme : code 502

Cause probable : mauvaise réponse du maillon suivant, coupable soit le site, soit un canal proxy instable. À vérifier en premier : la requête croisée — le même site en direct et le même proxy vers un site stable.

Symptôme : code 504

Cause probable : temps d'attente écoulé, il faut comprendre — connexion ou réponse. À vérifier en premier : des connect timeout et read timeout séparés, pour voir quelle étape a traîné.

Symptôme : code 403 via le proxy

Cause probable : limites du proxy, restriction géographique ou port interdit. À vérifier en premier : le corps de la réponse pour identifier la source de l'interdiction et le panneau de contrôle du proxy pour repérer des limites épuisées.

Symptôme : connection reset ou ECONNRESET

Cause probable : l'une des parties a fermé de force la connexion, souvent un proxy surchargé ou un canal instable. À vérifier en premier : l'étape de la rupture d'après la dernière ligne de curl -v et la répétabilité du problème sur une série de requêtes.

Symptôme : EOF, empty reply

Cause probable : le flux de données s'est interrompu avant la fin de la réponse. À vérifier en premier : à quel segment la rupture a eu lieu — avant ou après la réponse au CONNECT.

Symptôme : connect timeout

Cause probable : impossible d'établir la connexion, adresse inaccessible ou port fermé. À vérifier en premier : l'accessibilité de l'adresse du proxy et l'exactitude du port.

Symptôme : read timeout

Cause probable : la connexion existe, mais la réponse n'arrive pas, le site traite longtemps ou est bloqué. À vérifier en premier : votre read timeout n'est-il pas trop petit et le site n'est-il pas surchargé.

Conseil : Imprimez ce tableau ou enregistrez-le dans vos notes. Au moment d'une vraie erreur, sous pression, on oublie facilement la logique. Un aide-mémoire prêt à l'emploi économise nerfs et temps.

✅ Vérification : Passez en revue chaque erreur récente avec le tableau. Pour chacune, vous devez connaître la première action de vérification.

Vérification du résultat : la check-list du diagnosticien

Assurez-vous d'avoir maîtrisé toutes les compétences clés. Parcourez la check-list.

• Vous savez répondre en quelques secondes à la question : qui a envoyé l'erreur — le proxy ou le site.
• Vous comprenez la différence entre 407 et 401 et savez corriger l'authentification, y compris les caractères spéciaux dans le mot de passe.
• Vous distinguez un 502 du site d'un 502 du proxy par la vérification croisée.
• Vous séparez connect timeout et read timeout et savez ce que chacun signifie.
• Vous comprenez pourquoi tunnel connection failed n'arrive qu'en HTTPS et savez lire la réponse au CONNECT.
• Vous reconnaissez les trois causes de 403 venant du proxy : limites, géo et port.
• Vous diagnostiquez les ruptures de connexion par l'étape à laquelle elles sont survenues.
• Vous lisez la sortie de curl -v ligne par ligne et tracez les frontières client-proxy-serveur.

Comment vous tester

1. Prenez trois logs réels avec des erreurs différentes.
2. Pour chacun, déterminez le maillon coupable en une minute.
3. Nommez la première action de vérification selon le tableau.
4. Si vous avez réussi les trois, le diagnostic est maîtrisé.

✅ Vérification : L'indicateur de réussite, c'est que vous ne paniquez plus à la vue d'une erreur de proxy, mais que vous la décomposez calmement par maillons de la chaîne.

Erreurs typiques et solutions

Problème : je change de proxy à la moindre erreur

Cause : pas d'habitude de vérification croisée. Solution : faites toujours une requête de contrôle en direct et vers un site stable avant de modifier la configuration. La moitié des erreurs s'avèrent être du côté du site.

Problème : un mot de passe avec arobase casse la connexion

Cause : le caractère spécial n'est pas encodé et casse la chaîne. Solution : appliquez l'encodage URL au mot de passe ou utilisez un paramètre d'authentification séparé au lieu de l'inscrire dans l'adresse.

Problème : je confonds 407 et 401

Cause : je ne distingue pas l'authentification du proxy de celle du site. Solution : rappelez-vous — 407 vient toujours du proxy, 401 toujours du site. Vérifiez quel en-tête vous envoyez : Proxy-Authorization ou Authorization.

Problème : un timeout trop strict coupe des requêtes normales

Cause : le read timeout est réglé trop petit. Solution : séparez le connect timeout et le read timeout, donnez au read de la marge pour les pages lentes.

Problème : tunnel connection failed sur un port non standard

Cause : le proxy interdit CONNECT vers ce port. Solution : utilisez un port standard pour les connexions sécurisées ou renseignez-vous sur la liste des ports autorisés auprès du proxy.

Problème : je vois un 502 et je pense que le proxy est mort

Cause : je n'ai pas vérifié qui a envoyé le 502. Solution : vérification croisée. Souvent, le 502 vient d'un site cible surchargé et le proxy est en bon état.

Problème : j'ai révélé identifiant et mot de passe dans un log

Cause : j'ai partagé la sortie de curl -v sans nettoyage. Solution : masquez toujours la ligne d'autorisation avant d'envoyer un log à quiconque, et si possible changez les données compromises.

Problème : je confonds une rupture de connexion avec un timeout

Cause : je ne distingue pas reset et timeout. Solution : regardez le texte de l'erreur. Reset — fermeture active par l'autre partie, timeout — expiration de votre attente. Ce sont des causes différentes.

Fonctionnalités supplémentaires pour les avancés

Journalisation permanente

Configurez la sauvegarde de logs détaillés de toutes les requêtes proxy dans votre application. Ainsi, lorsqu'une erreur survient, vous aurez déjà un historique et n'aurez pas à reproduire le problème. Notez le code de réponse, l'étape de la rupture et le temps d'exécution.

Classification automatique des erreurs

Dans le code, vous pouvez créer une fonction qui, d'après le type d'exception et le code de réponse, classe immédiatement l'erreur dans le bon maillon. Par exemple, ConnectTimeout — segment de connexion, ReadTimeout — segment de réponse, ProxyError avec tunnel — couche proxy. Cela accélère la réaction dans les systèmes automatisés.

Collecte de statistiques de stabilité

Tenez des métriques : proportion de requêtes réussies, proportion de ruptures, temps de réponse moyen. Une dégradation brutale des métriques vous alertera avant que vous ne rencontriez le problème manuellement.

Conseil : Séparez les métriques par maillon. Comptez séparément les erreurs d'établissement de connexion et les erreurs à l'étape de réponse. Vous verrez ainsi immédiatement ce qui se dégrade — l'accès au proxy ou la communication avec les sites.

⚠️ Attention : En construisant un traitement automatique, ne le transformez pas en répétitions infinies de la même requête. La logique de retry est un vaste sujet à part entière avec ses propres règles, lié notamment au code 429. Un article dédié lui est consacré, et il vaut la peine de l'étudier séparément.

FAQ : questions fréquentes sur le diagnostic

Comment comprendre rapidement que c'est le proxy qui est en cause et non mon code ?

Faites la même requête directement, sans proxy. Si en direct tout fonctionne et que via le proxy non, le problème vient de la couche proxy ou de son interaction avec le site. Cela élimine la moitié des hypothèses en une minute.

Pourquoi j'obtiens 407 alors que j'ai saisi le bon mot de passe ?

Il y a probablement dans le mot de passe des caractères spéciaux qui cassent la chaîne de connexion. Appliquez l'encodage URL au mot de passe ou transmettez les données via un paramètre d'authentification séparé, plutôt que dans l'adresse.

Le code 502 signifie-t-il toujours que le proxy est cassé ?

Non. Le 502 peut aussi être envoyé par le site cible s'il a mal répondu. Faites une vérification croisée : le même site en direct et le même proxy vers un site stable. L'intersection des résultats désignera le coupable.

Quelle est la différence entre connect timeout et read timeout ?

Le connect timeout est l'attente d'établissement de la connexion. Le read timeout est l'attente de la réponse une fois la connexion établie. Séparez-les dans le client et vous verrez immédiatement quelle étape a traîné.

Pourquoi tunnel connection failed n'arrive-t-il qu'en HTTPS ?

Parce que pour les sites sécurisés, le client demande au proxy de construire un tunnel via la commande CONNECT. En HTTP classique, cette commande n'existe pas. Si le tunnel ne s'est pas construit, cette erreur arrive, et elle n'est possible qu'en HTTPS.

Comment distinguer un 403 du proxy d'un 403 du site ?

Regardez le corps de la réponse. Une page soignée du site signifie une interdiction du site. Une page technique ou une mention du proxy signifie une interdiction de l'intermédiaire. Confirmez par une requête directe vers le site.

Que faire en cas de ruptures de connexion aléatoires ?

Déterminez d'abord la répétabilité : faites une série de requêtes et comptez la proportion de ruptures. Des ruptures isolées sont une instabilité réseau tolérable. Des ruptures massives sont un problème systémique du proxy ou du canal.

Comment partager en sécurité un log curl -v pour obtenir de l'aide ?

Masquez impérativement la ligne avec l'autorisation du proxy et tout en-tête sensible avant l'envoi. Sinon, vous révélerez votre identifiant et votre mot de passe. En cas de doute, changez les données compromises.

Pourquoi mes requêtes normales se coupent-elles parfois par timeout ?

Le read timeout est probablement réglé trop strict, et vous coupez des réponses lentes mais valides. Augmentez le read timeout avec de la marge, et laissez le connect timeout petit.

Où lire sur le code 429 et les retries ?

Le code 429 et les stratégies de retry sont un vaste sujet à part entière, sans lien direct avec les défaillances de la couche proxy. Un article dédié lui est consacré, étudiez-le séparément du diagnostic des erreurs de proxy.

Conclusion : ce que vous avez maîtrisé et vers quoi aller ensuite

Félicitations. Vous avez parcouru le chemin depuis la perplexité devant des codes mystérieux jusqu'à un diagnostic pas à pas assuré. Rappelons ce qui est désormais dans votre arsenal.

Résumé des actions réalisées. Vous avez appris à diviser la chaîne en trois maillons — client, proxy et serveur — et à déterminer où exactement l'erreur est apparue. Vous avez élucidé le code 407 et l'authentification du proxy, y compris les caractères spéciaux sournois dans le mot de passe. Vous avez compris la double nature du 502 et la méthode de vérification croisée. Vous avez maîtrisé la séparation des connect et read timeouts pour le 504. Vous avez élucidé la méthode CONNECT et l'erreur tunnel connection failed en HTTPS. Vous avez appris à reconnaître les trois causes de 403 venant du proxy et à diagnostiquer les ruptures de connexion par étape. Et enfin, vous avez maîtrisé la compétence principale — la lecture de la sortie curl -v ligne par ligne, avec un tracé précis des frontières entre les maillons.

Que faire ensuite. Ancrez la compétence par la pratique. Chaque fois que vous rencontrez une erreur de proxy, ne devinez pas, mais décomposez-la calmement par maillons à l'aide du tableau de diagnostic. Après une semaine de cette pratique, le diagnostic deviendra automatique.

Vers quoi évoluer. L'étape logique suivante est d'étudier le code 429 et les stratégies de retry bien pensées, à laquelle un article dédié est consacré. Ensuite, approfondissez la classification automatique des erreurs dans le code et la collecte de métriques de stabilité. Cela fera de vous non plus quelqu'un qui éteint des incendies, mais un ingénieur qui anticipe les problèmes à l'avance.

Conseil : Enregistrez ce guide et le tableau de diagnostic dans vos favoris. Revenez-y à chaque nouvelle erreur, jusqu'à ce que la logique devienne votre seconde nature. La confiance en diagnostic vient précisément par la répétition. Vous allez y arriver.