Quand une requête échoue sans qu’on sache pourquoi
La plupart des « l’API est cassée » sont une requête qui n’a jamais dit qui elle était. La réponse le dit en général — dans la partie que personne ne lit.
API Post/Get couvre toutes les méthodes HTTP, range les requêtes en collections et dossiers, gère en-têtes et autorisation, et affiche le corps de la réponse avec coloration syntaxique. Les raccourcis clavier accélèrent le cycle de répétition dès qu’on les connaît.
Lisez toute la réponse, pas le statut
L’habitude qui fait gagner le plus de temps : ouvrir le corps de la réponse en cas d’échec au lieu de réagir au statut rouge. Les API écrites par des humains y mettent la raison, et c’est souvent une phrase qui clôt l’enquête.
Vérifiez ensuite les en-têtes des deux côtés. Une requête envoyée sans Content-Type: application/json est la cause unique la plus fréquente d’un 400 apparemment inexplicable : le serveur a reçu votre JSON comme du texte brut et n’a pas pu l’analyser.
Les quatre qui veulent dire quelque chose de précis
- 401 — vous ne vous êtes pas authentifié. Jeton absent, mal formé, ou dans le mauvais en-tête.
- 403 — vous vous êtes authentifié et n’avez pas le droit. Autre problème, autre correctif ; cessez de renvoyer le jeton.
- 404 — sur un endpoint dont vous savez qu’il existe, cela signifie souvent qu’une variable de chemin s’est résolue à vide. Vérifiez que
{{user_id}}a bien une valeur dans l’environnement choisi. - 422 — la requête a été comprise et les données refusées. Le corps nomme presque toujours le champ.
Un 500 est le seul qui soit vraiment le problème d’en face, et même là il vaut la peine d’envoyer la même requête sans les champs optionnels avant de signaler.
L’authentification, là où part le plus de temps
Réglez l’autorisation au niveau du dossier plutôt que par requête. Répéter un jeton bearer sur dix-neuf requêtes, c’est en mettre dix-neuf à jour à chaque rotation — et celle que vous oubliez est celle que vous déboguerez vingt minutes.
Et gardez le jeton dans une variable d’environnement au lieu de le taper dans l’en-tête. Ainsi changer d’environnement change aussi d’identité, ce que vous vouliez en changeant.
Questions fréquentes
J’obtiens un 400 et la requête semble correcte. Et maintenant ?
Vérifiez que vous envoyez Content-Type: application/json. Un corps JSON reçu comme texte brut produit exactement cela : une requête qui a l’air juste et un serveur incapable de l’analyser.
Quelle différence entre 401 et 403 ?
401 signifie que vous ne vous êtes pas authentifié — jeton manquant ou mal formé. 403 signifie que vous l’êtes et que vous n’avez pas le droit. Renvoyer le jeton règle le premier et ne fait rien au second.
Où doit vivre le jeton d’authentification ?
Dans une variable d’environnement, appliquée au niveau du dossier. Le taper dans chaque requête impose de toutes les mettre à jour à chaque rotation, et celle qu’on oublie devient vingt minutes de débogage.
