Réseau
Référence des codes de sortie de curl
Référence complète des exit code (codes de sortie) de la commande curl : significations, causes fréquentes et solutions pour les développeurs qui déboguent des pipelines CI/CD et des scripts shell. Inclut un outil de recherche — saisissez un numéro de code pour voir instantanément les détails.
Tableau de référence des exit codes de curl
| Code | Nom de la constante | Signification | Causes fréquentes |
|---|---|---|---|
| Erreurs de connexion / initialisation | |||
| 1 | CURLE_UNSUPPORTED_PROTOCOL | Indique que curl ne prend pas en charge le protocole spécifié dans l'URL. | Se produit avec un binaire curl compilé sans ce protocole activé (par exemple gopher, ldap), ou en cas de faute de frappe dans le schéma de l'URL. |
| 2 | CURLE_FAILED_INIT | Indique que l'initialisation interne de curl a échoué. | Un échec d'initialisation de bas niveau peu fréquent, généralement causé par un manque de mémoire ou un environnement anormal. |
| 3 | CURLE_URL_MALFORMAT | Indique que l'URL spécifiée est mal formée et que curl ne peut pas l'interpréter. | Se produit lorsque le schéma de l'URL est manquant (par exemple http://) ou qu'elle contient des caractères invalides. |
| 5 | CURLE_COULDNT_RESOLVE_PROXY | Indique que curl n'a pas réussi à résoudre le nom d'hôte du serveur proxy spécifié. | Causé par une faute de frappe dans le nom d'hôte passé à --proxy, ou une défaillance DNS propre au proxy. |
| 6 | CURLE_COULDNT_RESOLVE_HOST | Indique que curl n'a pas réussi à résoudre (DNS) le nom d'hôte du serveur de destination. | Généralement causé par une faute de frappe dans le nom de domaine, une panne du serveur DNS, ou une exécution dans un environnement hors ligne. |
| 7 | CURLE_COULDNT_CONNECT | Indique que le nom d'hôte a été résolu, mais que curl n'a pas réussi à établir une connexion TCP avec le serveur. | Se produit à cause d'un numéro de port incorrect, d'un pare-feu bloquant la connexion, ou parce que le serveur est hors service. |
| 8 | CURLE_WEIRD_SERVER_REPLY | Indique que curl a reçu du serveur une réponse inattendue qu'il n'a pas pu interpréter. | Fréquent lorsqu'un serveur FTP renvoie une réponse non standard, ou lorsque curl se connecte accidentellement à un serveur utilisant un autre protocole. |
| 9 | CURLE_REMOTE_ACCESS_DENIED | Indique que curl s'est connecté au serveur mais que l'accès a été refusé. | Se produit en cas de permissions insuffisantes sur un répertoire FTP, ou lorsque le serveur applique une restriction d'IP. |
| Erreurs de transfert de données | |||
| 18 | CURLE_PARTIAL_FILE | Indique que le transfert a été interrompu avant d'être terminé, si bien que seule une partie du fichier a été reçue. | Se produit lors d'une brève coupure réseau, ou lorsque le serveur ferme la connexion avant d'atteindre le Content-Length annoncé. |
| 23 | CURLE_WRITE_ERROR | Indique que l'écriture des données sur le disque local ou vers la destination du callback a échoué. | Se produit lorsque le disque est plein, ou que curl ne dispose pas des droits d'écriture sur le fichier de sortie. |
| 26 | CURLE_READ_ERROR | Indique que la lecture du fichier local à téléverser a échoué. | Se produit lorsque le fichier spécifié avec -T/--upload-file n'existe pas, ou que curl n'a pas les droits de lecture dessus. |
| 52 | CURLE_GOT_NOTHING | Indique que curl s'est connecté au serveur mais n'a reçu strictement aucune réponse. | Généralement causé par un plantage du processus serveur en cours de requête, ou une mauvaise configuration renvoyant une réponse vide. |
| 55 | CURLE_SEND_ERROR | Indique que l'envoi de données sur le réseau a échoué. | Se produit lorsque le correspondant se déconnecte immédiatement après l'établissement de la connexion, ou en raison d'un problème sur l'interface réseau locale. |
| 56 | CURLE_RECV_ERROR | Indique que la réception de données depuis le réseau a échoué. | Fréquemment observé lorsque le correspondant réinitialise de manière inattendue la connexion en cours de transfert (Connection reset by peer). |
| 63 | CURLE_FILESIZE_EXCEEDED | Indique que la taille du fichier a dépassé la limite définie avec --max-filesize. | Se produit lorsque la réponse s'avère plus volumineuse que prévu et atteint la limite de sécurité configurée. |
| 78 | CURLE_REMOTE_FILE_NOT_FOUND | Indique que le fichier spécifié n'existe pas sur le serveur distant (par exemple en FTP). | Se produit à cause d'une faute de frappe dans le chemin FTP, ou lorsque le fichier cible a déjà été supprimé ou déplacé. |
| Erreurs de certificat SSL/TLS | |||
| 35 | CURLE_SSL_CONNECT_ERROR | Indique qu'un problème est survenu pendant la négociation SSL/TLS, empêchant l'établissement de la connexion. | Souvent causé par une incompatibilité entre les versions de TLS ou les suites cryptographiques prises en charge par le serveur et le client. |
| 51 | CURLE_PEER_FAILED_VERIFICATION | Indique que la vérification du certificat du serveur a échoué (par exemple, le certificat ne correspond pas au nom d'hôte). | Se produit lors de l'accès à un certificat auto-signé, ou lorsque le Common Name/SAN du certificat diffère du nom d'hôte de destination. |
| 58 | CURLE_SSL_CERTPROBLEM | Indique un problème avec le certificat client spécifié localement. | Généralement causé par un format invalide du fichier de certificat passé avec --cert, ou une phrase secrète incorrecte. |
| 60 | CURLE_SSL_CACERT | Indique que curl n'a pas pu vérifier la chaîne de certificats de l'autorité de certification (CA) utilisée pour valider le certificat du serveur. | Se produit lorsque le lot de certificats CA est obsolète, ou qu'une CA auto-signée (comme celle d'un proxy d'entreprise) n'est pas enregistrée dans le magasin de confiance. -k/--insecure est une solution de contournement, mais son usage en production est déconseillé. |
| Erreurs HTTP / authentification | |||
| 22 | CURLE_HTTP_RETURNED_ERROR | Indique que, avec l'option -f/--fail spécifiée, la réponse HTTP a renvoyé un statut d'erreur de 400 ou plus. | Déclenché intentionnellement dans des scripts CI/CD utilisant curl -f afin de détecter comme un échec un statut d'erreur de l'API. |
| 67 | CURLE_LOGIN_DENIED | Indique que la connexion (authentification) au serveur a été refusée. | Généralement causé par un nom d'utilisateur ou un mot de passe incorrect, ou un verrouillage de compte sur des protocoles comme FTP/SMTP. |
| Autres | |||
| 27 | CURLE_OUT_OF_MEMORY | Indique que curl n'a pas réussi à allouer de la mémoire pendant l'exécution. | Une situation rare, comme tenter de traiter un fichier énorme sur un système à la mémoire limitée. |
| 28 | CURLE_OPERATION_TIMEDOUT | Indique que l'opération ne s'est pas terminée dans le délai fixé avec --connect-timeout/--max-time, etc. | L'une des erreurs les plus fréquentes en CI, causée par une réponse lente du serveur, une latence réseau, ou une valeur de délai d'attente réglée trop courte. |
| 47 | CURLE_TOO_MANY_REDIRECTS | Indique que le nombre de redirections a dépassé la limite fixée avec --max-redirs. | Se produit lors d'une boucle de redirection (301/302 se redirigeant de façon circulaire), ou d'une chaîne de redirections légitime plus longue que la limite par défaut (50). |
Astuces
- Vous pouvez vérifier l'exit code juste après avec
$?(Bash) ou%errorlevel%(Windows). Dans les scripts shell, une bifurcation telle quecurl ... || echo "failed with $?"est un motif bien pratique. - Les codes 28 (délai dépassé) et 7 (échec de connexion) sont souvent confondus, mais le 28 survient lorsque la réponse est lente après l'établissement de la connexion, tandis que le 7 survient lorsque la connexion TCP elle-même n'a jamais pu être établie.
- Si vous obtenez un 60 (erreur de certificat CA), ne le contournez pas simplement avec
-k/--insecure— vérifiez d'abord si votre lot de certificats CA (ca-certificates) est à jour. Utiliser -k de façon systématique en production augmente le risque d'attaques de l'homme du milieu. - Le code 22 (erreur HTTP) ne survient que si vous ajoutez l'option
-f/--fail. Sans elle, curl renvoie l'exit code 0 (succès) même pour une réponse 404 ou 500 : ajoutez donc toujours -f si vous voulez que la CI détecte les échecs.
FAQ
Juste après l'exécution de la commande curl, vérifiez-le avec
echo $? sous Bash/Zsh, echo %errorlevel% dans l'invite de commandes Windows, ou $LASTEXITCODE dans PowerShell.Commencez par revoir les valeurs de
--connect-timeout et --max-time, et augmentez-les si nécessaire. Si le serveur répond durablement lentement, vérifiez aussi sa charge et le chemin réseau (proxy, VPN, etc.).Non, ce sont des choses différentes. Les codes de statut HTTP (comme 404 ou 500) sont des réponses au niveau du protocole renvoyées par le serveur, tandis que les exit codes de curl indiquent le résultat de l'exécution de la commande curl elle-même (échec de connexion, délai dépassé, etc.). Par défaut, curl traite les erreurs HTTP comme un exit code 0 (succès) : veillez donc à ne pas confondre les deux.
Ajoutez l'option
curl -f (--fail) pour que curl renvoie l'exit code 22 dès que la réponse HTTP est égale ou supérieure à 400. Sans elle, récupérer avec succès une page d'erreur donne tout de même un exit code de 0.Le 6 (COULDNT_RESOLVE_HOST) est une erreur au niveau de la résolution DNS, lorsque le nom d'hôte n'a pas pu être converti en adresse IP. Le 7 (COULDNT_CONNECT) est une erreur où la résolution de nom a réussi, mais où la connexion TCP vers cette adresse IP n'a pas pu être établie.
Anecdote — Le système des exit codes de curl
curl est un outil en ligne de commande dont le développement a débuté en 1996 sous l'impulsion de Daniel Stenberg, initialement sous le nom « httpget ». Aujourd'hui, curl est préinstallé par défaut sur pratiquement toutes les distributions Linux, sur macOS ainsi que sur Windows 10 et versions ultérieures, ce qui en fait l'un des outils les plus fondamentaux pour les développeurs web.
Le système des exit codes correspond directement à l'énumération d'erreurs interne de libcurl, CURLcode, définie par une numérotation séquentielle débutant à `CURLE_OK` (succès, exit code 0). Les trous dans la numérotation s'expliquent par le fait que certains codes d'erreur ont été dépréciés ou fusionnés au fil du développement.
Fait intéressant, les exit codes de curl forment un système propre, indépendant de la convention générale POSIX (0 = succès, 1 = erreur générale). Cela signifie que, pour traiter de façon transversale les exit codes de plusieurs outils dans un script shell, il faut consulter individuellement le manuel de chaque outil pour en comprendre la signification.