L'appel échoue. Tout le monde décrète que le serveur est cassé, que l'API est en rade. On rejoue la requête à la main, dans un outil à part : elle passe. Dans l'application : elle échoue. Même URL, mêmes données envoyées. Pendant une heure, on relit le code qui construit le corps de la requête, ligne par ligne, sans rien trouver.
Le coupable n'était pas dans le contenu. Il était dans l'enveloppe. Un en-tête, Content-Type, annonçait du texte brut alors qu'on envoyait du JSON. Le serveur, très correctement, refusait de lire une lettre dont l'enveloppe mentait sur le contenu. On relisait la lettre. Le problème était sur l'enveloppe.
Une requête, c'est trois choses
On réduit souvent une requête HTTP à une URL. Elle en contient bien plus, et c'est cette ignorance qui coûte des heures.
Une requête, c'est d'abord une ligne : un verbe et une cible. GET /utilisateurs, POST /commandes. Le verbe dit l'intention, la cible dit sur quoi. C'est ensuite un paquet d'en-têtes, et c'est là que se joue l'essentiel : qui tu es (Authorization), ce que tu envoies (Content-Type), ce que tu sais recevoir (Accept), tes cookies, ta langue. Les en-têtes, ce sont les métadonnées qui disent au serveur comment lire tout le reste. C'est enfin, parfois, un corps : la charge utile, le JSON que tu poses dans un POST.
La réponse a exactement la même anatomie : un code de statut qui résume le sort de la demande, ses propres en-têtes, son propre corps. Et le drame se répète à chaque fois : on regarde le verbe, l'URL et le corps, et on oublie les en-têtes, précisément là où vit le contrat silencieux entre le client et le serveur.
Le verbe n'est pas décoratif
Le choix du verbe non plus n'est pas anodin. GET lit, sans rien changer : c'est une demande sûre, qu'on peut rejouer, mettre en cache, relancer sans risque. POST crée ou modifie : le rejouer, c'est risquer de commander deux fois. Toute une machinerie invisible, les caches, les proxys, les mécanismes de nouvelle tentative, fait confiance à cette distinction. Utilise un GET pour une action qui modifie, et un jour un cache te resservira un vieux résultat, ou un navigateur rejouera l'action tout seul. Le verbe n'est pas une étiquette, c'est une promesse sur laquelle d'autres comptent.
Ce que l'IA remplit, et ce qu'elle ignore
L'assistant t'écrit l'appel réseau en une ligne, et il remplit les en-têtes courants sans que tu y penses. Utile. Mais l'en-tête qui compte vraiment, c'est celui qui est propre à ton API : le schéma d'authentification maison, le Content-Type exact qu'elle exige, l'en-tête de version qu'elle réclame. Ça, c'est le contrat de ton domaine, il n'est écrit nulle part dans le code générique, et la machine ne peut pas l'inventer. Et le jour où la requête échoue, lire ce qui cloche, c'est lire les en-têtes un par un, ce qu'aucune génération ne commente pour toi. L'enveloppe, c'est là que l'humain débogue encore.
Ce que je te conseille
Quand une requête échoue, ne compare pas seulement l'URL et le corps entre le cas qui marche et celui qui casse : compare la requête entière, en-têtes compris. Neuf fois sur dix, la différence est dans l'enveloppe que personne ne regarde. Et choisis ton verbe pour ce qu'il signifie, pas par habitude : GET lit, POST change, parce que tout l'écosystème autour te croit sur parole.
Une requête ne se résume pas à ce que tu demandes. C'est aussi la façon dont tu le demandes, et cette façon, le serveur la lit avant tout le reste.
Ce satellite fait partie du dossier Navigateur. Juste avant lui, la connexion sécurisée : Le cadenas a une date de péremption. Le vocabulaire : la requête HTTP, l'en-tête HTTP, la méthode HTTP, le corps de requête et le code de statut HTTP.