Linux / Commande curl : requêtes HTTP, erreurs et téléchargement

curl transfère des données à partir d’une URL et permet d’examiner les réponses HTTP, de télécharger un fichier ou d’interroger une API. Par défaut, le corps reçu est écrit sur la sortie standard. Un transfert terminé peut donner un code de sortie 0 même si le serveur répond HTTP 404 ou 500 : vérifiez séparément l’état HTTP, le résultat de curl et le contenu attendu.

Lire les en-têtes avec HEAD ou GET

HTTP signifie Hypertext Transfer Protocol ; une API, Application Programming Interface, est une interface par laquelle un programme utilise un service. curl gère plusieurs protocoles, mais les exemples suivants concernent HTTP et HTTPS. Vérifiez curl --version et man curl pour les fonctions disponibles dans votre installation.

curl [OPTIONS] URL

curl -I https://example.com/

-I envoie une requête HEAD pour demander les en-têtes sans télécharger le corps comme une requête GET ordinaire. Le statut, le type de contenu et les éventuelles redirections peuvent aider au diagnostic, mais certains serveurs traitent HEAD différemment ou le refusent.

Si HEAD est refusé, effectuez un GET avant de conclure que la ressource manque. Pour enregistrer les en-têtes de ce GET et ignorer le corps :

curl -sS -D headers.txt -o /dev/null https://example.com/

Choisissez un nouveau nom dans un répertoire de travail pour headers.txt : un fichier existant peut être écrasé. -D écrit les en-têtes reçus ; -o /dev/null écarte le corps sous Linux. -s masque la progression et -S conserve les messages d’erreur lorsque -s est utilisé.

Distinguer état HTTP et code de sortie

curl -sS -o /dev/null -w '%{http_code}\n' https://example.com/

Si le serveur répond 200, la sortie de cet exemple est :

200

Cette sortie est conditionnelle : un HTTP 200 n’atteste pas que la page contient le texte attendu ni qu’une opération métier a réussi. Une page d’erreur applicative peut elle-même être servie avec ce statut. Si aucun code HTTP n’a été reçu, la valeur affichée peut être 000 ; ce n’est pas un statut renvoyé par un serveur HTTP. Lisez aussi l’erreur et le code de sortie du processus.

curl -fL https://example.com/
curl --fail-with-body -L https://example.com/

-f, ou --fail, traite les réponses HTTP à partir de 400 comme une erreur curl 22 et masque leur corps. --fail-with-body conserve le corps tout en signalant l’erreur 22 ; cette option existe depuis curl 7.76.0. Ne combinez pas les deux options. Le manuel signale des exceptions possibles dans certains échanges d’authentification : pour une automatisation critique, vérifiez aussi le statut et la donnée réellement attendus.

Dans un shell, récupérez le code de sortie immédiatement après la commande concernée. Une commande suivante, ou une chaîne de traitements mal contrôlée, peut masquer ce résultat. Un code de transfert et un code HTTP répondent à deux questions différentes.

Suivre une redirection et enregistrer un fichier

-L suit les redirections HTTP. Sans cette option, une réponse 301 ou 302 peut terminer le transfert avec succès sans fournir le document final recherché. Pour un téléchargement dans un répertoire de travail avec un nom nouveau :

curl -fL --connect-timeout 5 --max-time 30 -o example.html https://example.com/

-o choisit le fichier de destination ; il peut écraser un fichier existant. --connect-timeout limite la phase de connexion, tandis que --max-time borne la durée du transfert de cet exemple. Ces nombres sont des choix de diagnostic, à adapter à la ressource et au réseau, pas une garantie de succès.

Après un échec, ne consommez pas automatiquement le fichier comme un téléchargement complet : un fichier vide ou partiel peut rester. Après un succès, contrôlez le type et le contenu avant de l’utiliser. Télécharger un script ne justifie pas de le transmettre directement à un shell pour l’exécuter.

Ajouter un en-tête et préserver les secrets

curl -sS --fail-with-body -H 'Accept: application/json' https://example.com/

Cet en-tête annonce un format souhaité ; il ne transforme pas une page HTML en API JSON et le serveur peut répondre autrement. Utilisez l’URL et le contrat de l’API réellement concernée, puis vérifiez le type de contenu et le corps. Les URL d’exemple illustrent la syntaxe et ne promettent pas un service JSON.

Les jetons et mots de passe placés directement dans une commande peuvent apparaître dans l’historique ou la liste des processus. Les sorties détaillées et traces peuvent aussi contenir des données sensibles : protégez les fichiers et masquez les secrets avant de les partager. Évitez d’ajouter des en-têtes d’authentification à une requête de test qui n’en a pas besoin.

Avec des requêtes authentifiées, examinez les redirections et leurs destinations. Ne supposez pas que tous les en-têtes personnalisés restent privés lors d’un changement d’hôte ; des options comme --location-trusted élargissent encore la transmission des secrets. N’ajoutez pas ces réglages pour faire disparaître un échec de connexion.

HTTPS utilise TLS, Transport Layer Security, pour protéger la communication et vérifier l’identité du serveur. -k désactive des vérifications de certificat : ce n’est pas une correction ordinaire d’une erreur TLS. Vérifiez plutôt le nom, la date et la chaîne de confiance correspondant à votre environnement.

Le manuel officiel curl détaille chaque option, les limites de --fail et les codes de sortie. Pour une panne de nom, la lecture des réponses DNS avec dig permet d’examiner une autre étape de la requête.