Codes d'erreur curl : référence complète

Tableau de référence rapide

Erreur 6 : Impossible de résoudre l'hôte

Ce que cela signifie

Votre terminal affiche curl: (6) Could not resolve host. curl n'a pas pu résoudre le nom d'hôte en adresse IP — la recherche DNS a échoué avant toute tentative de connexion.

Causes

Les causes les plus courantes sont : une faute de frappe dans le nom d'hôte (par ex. curl https://apiexample.com au lieu de api.example.com), des problèmes de serveur DNS (votre DNS configuré est en panne ou inaccessible), pas de connexion réseau (Wi-Fi déconnecté, VPN non connecté), ou le domaine n'existe réellement pas.

Comment résoudre

D'abord, vérifiez que l'URL est correcte. Puis testez la résolution DNS directement : nslookup api.example.com ou dig api.example.com. Si le DNS échoue, essayez un serveur DNS différent : curl --dns-servers 8.8.8.8 https://api.example.com. Vérifiez votre /etc/resolv.conf ou vos paramètres réseau. Si vous êtes derrière un VPN d'entreprise, assurez-vous que le DNS interne peut résoudre l'hôte.

$ curl https://api.exmple.com/users

Erreur 7 : Échec de connexion

Ce que cela signifie

Votre terminal affiche curl: (7) Failed to connect to host port: Connection refused. curl a résolu le nom d'hôte mais n'a pas pu établir une connexion TCP avec le serveur — la connexion a été activement refusée ou a expiré au niveau TCP.

Causes

Les causes courantes incluent : le serveur est arrêté ou ne fonctionne pas, un pare-feu bloque le port (vérifiez les pare-feu locaux et côté serveur), le port est incorrect (par ex. le service tourne sur 8080 mais vous vous connectez au 443), ou le backlog d'écoute du serveur est plein sous forte charge.

Comment résoudre

Vérifiez que le serveur fonctionne : ping api.example.com et telnet api.example.com 443. Vérifiez si le bon port est ouvert : nmap -p 443 api.example.com. Désactivez temporairement le pare-feu local pour tester. Si vous utilisez Docker, assurez-vous que le port du conteneur est publié. Essayez en mode verbeux : curl -v https://api.example.com pour voir exactement où la connexion échoue.

$ curl https://localhost:8080/api

Erreur 22 : Erreur HTTP retournée

Ce que cela signifie

Votre terminal affiche curl: (22) The requested URL returned error. Le serveur a retourné un code d'état HTTP d'erreur (4xx ou 5xx) et curl a été invoqué avec -f ou --fail, ce qui indique à curl de traiter les erreurs HTTP comme des échecs.

Causes

L'erreur est déclenchée par des codes d'état HTTP comme 400 (Bad Request), 401 (Unauthorized), 403 (Forbidden), 404 (Not Found), ou 500 (Internal Server Error) — mais uniquement lorsque --fail est utilisé. Sans --fail, curl sort avec le code 0 même en cas d'erreurs HTTP. Causes courantes : mauvaise URL, authentification manquante, permissions insuffisantes, ou bugs côté serveur.

Comment résoudre

Exécutez curl sans --fail pour voir le corps complet de la réponse — il contient souvent le message d'erreur réel. Vérifiez le code d'état HTTP : curl -w "%{http_code}" -o /dev/null -s URL. Pour 401/403 : vérifiez votre token d'authentification ou clé API. Pour 404 : revérifiez le chemin de l'URL. Pour 500 : le problème est côté serveur.

$ curl --fail https://api.example.com/nonexistent

Erreur 28 : Opération expirée

Ce que cela signifie

Votre terminal affiche curl: (28) Operation timed out ou curl: (28) Connection timed out. L'opération a pris plus de temps que le temps autorisé. C'est l'erreur curl la plus courante — elle peut survenir lors de la résolution DNS, de la connexion TCP, du handshake SSL ou du transfert de données.

Causes

Les causes typiques incluent : un serveur lent ou surchargé qui ne répond pas à temps, une congestion réseau ou perte de paquets, un pare-feu qui abandonne silencieusement les paquets (pas de rejet, juste du silence), des valeurs de timeout trop strictes définies avec --connect-timeout ou --max-time, ou une mauvaise configuration du proxy causant des délais.

Comment résoudre

Augmentez le timeout : curl --connect-timeout 30 --max-time 120 URL. Utilisez le mode verbeux pour voir où ça bloque : curl -v URL. Testez la latence réseau : ping api.example.com et traceroute api.example.com. Si vous êtes derrière un proxy, essayez de le contourner : curl --noproxy '*' URL. Pour les transferts de gros fichiers, pensez à utiliser --retry 3 avec --retry-delay 5.

$ curl --connect-timeout 5 https://slow-api.example.com/data

Erreur 35 : Erreur de connexion SSL

Ce que cela signifie

Votre terminal affiche curl: (35) SSL connect error. Le handshake SSL/TLS a échoué — curl n'a pas pu établir une connexion sécurisée avec le serveur.

Causes

Causes courantes : incompatibilité de version TLS (le serveur exige TLS 1.3 mais votre curl ne supporte que TLS 1.2), incompatibilité de suite de chiffrement, mauvaise configuration SSL du serveur (certificat expiré présenté lors du handshake, chaîne incomplète), le serveur ne supporte pas réellement HTTPS sur le port donné, ou un proxy ou pare-feu intercepte la connexion SSL (MITM).

Comment résoudre

Forcez une version TLS spécifique : curl --tlsv1.2 URL ou curl --tlsv1.3 URL. Vérifiez ce que le serveur supporte : openssl s_client -connect api.example.com:443. Mettez à jour curl et OpenSSL vers les dernières versions. Si le serveur utilise un certificat auto-signé, c'est généralement l'erreur 60 — l'erreur 35 indique typiquement un échec de handshake au niveau du protocole.

$ curl https://legacy-server.example.com/api

Erreur 56 : Échec de réception — Connexion réinitialisée

Ce que cela signifie

Votre terminal affiche curl: (56) Recv failure: Connection reset by peer. La connexion a été établie avec succès, mais la réception des données a échoué — le serveur a fermé ou réinitialisé la connexion de manière inattendue pendant le transfert.

Causes

Cela arrive souvent quand : le serveur plante ou redémarre en cours de transfert, un load balancer ou proxy coupe la connexion (timeout d'inactivité, requête trop volumineuse), un pare-feu termine les connexions de longue durée, le serveur a un timeout keep-alive plus court que prévu, ou il y a une perturbation réseau entre le client et le serveur.

Comment résoudre

Réessayez la requête — les problèmes réseau transitoires sont la cause la plus courante. Utilisez le mode verbeux : curl -v URL pour voir le point exact de l'échec. Si l'erreur survient lors de gros uploads, essayez le transfert par morceaux : curl -H "Transfer-Encoding: chunked" URL. Pour les opérations Git affichant RPC failed; curl 56, augmentez le tampon : git config http.postBuffer 524288000.

$ curl https://api.example.com/large-download

Erreur 60 : Problème de certificat SSL

Ce que cela signifie

Votre terminal affiche curl: (60) SSL certificate problem: unable to get local issuer certificate. curl n'a pas pu vérifier le certificat SSL du serveur par rapport à son bundle CA (Autorité de Certification). Le handshake TLS s'est terminé au niveau du protocole, mais la validation du certificat a échoué.

Causes

Les causes les plus courantes : le serveur utilise un certificat auto-signé, le certificat a expiré, la chaîne de certificats est incomplète (certificats intermédiaires manquants), le bundle CA de curl est obsolète (courant sur les anciens systèmes ou dans les conteneurs Docker), ou le Common Name / SAN du certificat ne correspond pas au nom d'hôte demandé.

Comment résoudre

Mettez à jour le bundle CA : curl --cacert /path/to/cacert.pem URL. Téléchargez un bundle mis à jour depuis https://curl.se/ca/cacert.pem. Pour diagnostiquer : openssl s_client -connect api.example.com:443 -showcerts. Pour les certificats auto-signés en développement, utilisez curl -k URL (jamais en production — cela désactive toute vérification de certificat). Dans Docker, installez le package ca-certificates.

$ curl https://self-signed.example.com/api

Autres codes d'erreur

Comment déboguer les erreurs curl

Quand curl échoue, ces trois flags vous aident à identifier rapidement la cause racine — de la résolution DNS au handshake SSL en passant par le contenu de la réponse.

1. 1

   Activer la sortie verbeuse

   Exécutez curl -v URL pour voir le cycle complet requête/réponse : résolution DNS, connexion TCP, handshake TLS, en-têtes de requête envoyés et en-têtes de réponse reçus. C'est le flag de débogage le plus utile.

2. 2

   Vérifier le code d'état HTTP

   Exécutez curl -o /dev/null -s -w "%{http_code}" URL pour obtenir uniquement le code d'état HTTP (200, 404, 500, etc.) sans le corps de la réponse. Utile pour les vérifications rapides et les scripts.

3. 3

   Afficher les erreurs silencieusement

   Exécutez curl -sS URL pour supprimer la barre de progression (-s) tout en continuant d'afficher les erreurs (-S). Parfait pour les scripts où vous voulez une sortie propre mais devez détecter les échecs.

Questions fréquemment posées