Comment déboguer les erreurs d’API REST : CORS, 401, 403, 404, 415 et timeouts

Par Sayaib SarkarMis à jour le 7 min de lecture

Sur cette page 9 sections

Réponse courte : reproduisez la requête en échec en dehors de votre application, lisez le code de statut et le corps de la réponse avant toute chose, puis changez une seule chose à la fois. La plupart des bugs d’API relèvent d’une poignée de schémas, et le code de statut vous dit lequel. Si le navigateur indique « blocked by CORS policy » mais que la même requête fonctionne dans un client d’API, le problème vient des en-têtes CORS du serveur, pas de votre requête.

Ce guide passe en revue les erreurs que les développeurs rencontrent le plus souvent en intégrant une API, ce que chacune signifie vraiment et comment confirmer la cause en quelques minutes depuis VS Code.

Étape 1 : reproduire la requête en dehors de votre application

Votre application ajoute des couches : une bibliothèque HTTP, des intercepteurs, un proxy, le navigateur. Retirez-les d’abord.

  1. Dans le navigateur, ouvrez les DevTools → Network, faites un clic droit sur la requête en échec et choisissez Copy → Copy as cURL.
  2. Dans VS Code, ouvrez le client d’API REST de DevSnip Pro et collez la commande cURL dans la barre d’adresse. La méthode, les en-têtes et le corps sont importés.
  3. Envoyez-la. Vous pouvez maintenant changer un en-tête à la fois et voir l’effet immédiatement.

Si la requête fonctionne ici mais échoue dans le navigateur, passez à la section CORS. Si elle échoue dans les deux, le code de statut ci-dessous vous indique où regarder.

Lire le code de statut et le corps

Avant de modifier le code, lisez ce que le serveur a renvoyé. Beaucoup d’API expliquent le problème dans le corps de la réponse, par exemple {"error": "invalid_token", "error_description": "The access token expired"}.

StatutCe que cela signifie généralementÀ vérifier d’abord
400 Bad RequestLe corps ou les paramètres sont invalidesLe corps de la réponse ; les champs obligatoires ; la syntaxe JSON
401 UnauthorizedAucun identifiant valide n’a été envoyéL’en-tête Authorization ; l’expiration du token
403 ForbiddenLes identifiants sont valides mais pas autorisés à faire celaLes scopes ou rôles du token ; les permissions de la clé d’API
404 Not FoundMauvaise URL, ou la ressource n’existe pasL’URL de base, le chemin, la barre oblique finale, la version de l’API
405 Method Not AllowedBonne URL, mauvaise méthodeGET ou POST ; l’en-tête de réponse Allow
415 Unsupported Media TypeLe serveur ne sait pas lire le format du corpsL’en-tête Content-Type
422 Unprocessable EntityJSON valide, mais la validation a échouéLa liste des erreurs de champs dans le corps de la réponse
429 Too Many RequestsLimite de débit atteinteL’en-tête Retry-After
5xxLe serveur a échouéLes logs du serveur ; si une autre entrée fonctionne

401 Unauthorized : les identifiants ne sont pas arrivés ou ne sont pas valides

  • L’en-tête est-il seulement présent ? Certains clients HTTP suppriment Authorization en suivant une redirection vers un autre hôte. Vérifiez la requête réellement envoyée, pas le code qui la construit.
  • Le format est-il correct ? La plupart des API attendent Authorization: Bearer <token> avec exactement une espace, et le mot Bearer une seule fois. Un Bearer Bearer … doublé est un bug courant quand le token est stocké avec son préfixe.
  • Le token a-t-il expiré ? Collez un JWT dans le JWT Decoder & Signer de DevSnip Pro : il affiche l’en-tête et les claims et vérifie exp. Comparez aussi aud (audience) et iss (émetteur) avec ce qu’attend l’API. Le décodeur s’exécute en local : un vrai token ne part jamais vers un site web.

403 Forbidden : qui vous êtes est correct, ce que vous faites ne l’est pas

Le serveur sait qui vous êtes, mais votre token ou votre clé n’a pas la permission pour cette opération. Regardez les scopes ou rôles dans les claims du token, les permissions de la clé d’API, et si la ressource appartient à un autre compte ou tenant. Réessayer la même requête avec un nouveau token n’aidera pas, sauf si ce nouveau token a plus de permissions.

Certains serveurs renvoient aussi 403 quand un pare-feu ou un WAF bloque la requête (par exemple en l’absence de User-Agent). Dans ce cas, le corps de la réponse ressemble souvent à une page d’erreur HTML plutôt qu’à du JSON.

404 Not Found et 405 Method Not Allowed

Comparez l’URL caractère par caractère avec la documentation de l’API :

  • L’URL de base et la version de l’API (/v1/ ou /v2/).
  • Une barre oblique finale : /users et /users/ sont des routes différentes sur beaucoup de serveurs.
  • Des paramètres de chemin jamais substitués, comme /users/undefined ou /users/{id}.

Utiliser des variables d’environnement comme {{baseUrl}} pour l’hôte, au lieu de le coder en dur dans chaque requête, élimine toute une catégorie de ces erreurs. Si le chemin est correct et que vous obtenez 405, la route existe mais pas pour cette méthode ; l’en-tête de réponse Allow liste celles qu’elle accepte.

415 et 400 : le corps n’est pas ce qu’attend le serveur

Un corps JSON nécessite Content-Type: application/json. Sans lui, beaucoup de frameworks ne parsent pas du tout le corps, et votre gestionnaire le voit vide. Cela se manifeste par un 415, ou par un 400 qui se plaint de champs obligatoires manquants alors que vous les avez envoyés.

HTTP
POST /v1/users HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer <token>

{"name": "Ada", "role": "admin"}

Si le serveur attend plutôt des données de formulaire, envoyez application/x-www-form-urlencoded (c’est généralement le cas des endpoints de tokens OAuth). Pour vérifier un corps JSON par rapport au schéma de l’API avant de l’envoyer, utilisez le JSON Schema Validator de DevSnip Pro : il liste chaque violation avec son chemin.

CORS : « blocked by CORS policy »

CORS n’est appliqué que par les navigateurs. curl, Postman, les applications mobiles et les appels de serveur à serveur l’ignorent, ce qui explique qu’une requête puisse fonctionner dans un client d’API et échouer dans votre application web. La correction se fait toujours côté serveur : il doit envoyer les bons en-têtes Access-Control-* pour l’origine de votre page.

Les causes courantes :

  • Pas d’en-tête Access-Control-Allow-Origin, ou un en-tête avec une autre origine. http://localhost:3000 et http://localhost:5173 sont des origines différentes.
  • La requête préalable OPTIONS échoue. Les requêtes avec un corps JSON ou un en-tête Authorization déclenchent une requête préalable (preflight). Si le serveur y répond par 401, 404 ou 405 (souvent parce que le middleware d’authentification s’exécute avant CORS), le navigateur bloque la vraie requête.
  • Des identifiants avec un joker. Avec des cookies (credentials: 'include'), le serveur doit renvoyer l’origine exacte et Access-Control-Allow-Credentials: true. Access-Control-Allow-Origin: * n’est pas autorisé.
  • Des erreurs sans en-têtes CORS. Si le serveur renvoie un 500 sans en-têtes CORS, le navigateur signale une erreur CORS et masque la vraie. Renvoyez aussi les en-têtes CORS sur les réponses d’erreur.

Le CORS Builder & Debugger de DevSnip Pro propose trois modes pour cela : collez l’erreur de la console pour obtenir la cause probable et la correction, collez les en-têtes de réponse pour les vérifier comme le ferait un navigateur, ou générez une configuration correcte pour Express, NestJS, Next.js, Fastify, nginx ou FastAPI.

Timeouts et requêtes qui ne se terminent jamais

  • Vérifiez que quelque chose écoute bien. Le Port & Network Toolkit de DevSnip Pro montre quels ports locaux sont libres : si le port que devrait utiliser votre API est libre, le serveur n’y tourne pas.
  • Une requête vers localhost depuis un téléphone ou un émulateur va vers l’appareil lui-même, pas vers votre ordinateur. Utilisez l’adresse LAN de votre machine, ou l’alias de l’émulateur pour l’hôte.
  • Les grosses réponses et les endpoints lents peuvent nécessiter un délai plus long. Dans DevSnip Pro, devsnip.apiTimeout définit la valeur par défaut (30 secondes), un délai propre à une requête la remplace, et Cancel arrête une requête avant la fin.

Puis corriger dans le code

Une fois qu’une requête fonctionne dans le client d’API, générez le même appel en JavaScript (fetch ou Axios), Python, Go, Java ou C# et comparez-le avec votre code. La différence tient généralement à un en-tête, à l’encodage du corps ou à l’URL.

Essayez-le dans votre propre éditeur

Gratuit, sans compte, en local. Pour VS Code 1.93+ et les IDE JetBrains sous Windows, macOS ou Linux.

code --install-extension sayaib.hue-console