Comment déboguer les erreurs d’API REST : CORS, 401, 403, 404, 415 et timeouts
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.
Votre application ajoute des couches : une bibliothèque HTTP, des intercepteurs, un proxy, le navigateur. Retirez-les d’abord.
- Dans le navigateur, ouvrez les DevTools → Network, faites un clic droit sur la requête en échec et choisissez Copy → Copy as cURL.
- 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.
- 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.
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"}.
| Statut | Ce que cela signifie généralement | À vérifier d’abord |
|---|---|---|
400 Bad Request | Le corps ou les paramètres sont invalides | Le corps de la réponse ; les champs obligatoires ; la syntaxe JSON |
401 Unauthorized | Aucun identifiant valide n’a été envoyé | L’en-tête Authorization ; l’expiration du token |
403 Forbidden | Les identifiants sont valides mais pas autorisés à faire cela | Les scopes ou rôles du token ; les permissions de la clé d’API |
404 Not Found | Mauvaise URL, ou la ressource n’existe pas | L’URL de base, le chemin, la barre oblique finale, la version de l’API |
405 Method Not Allowed | Bonne URL, mauvaise méthode | GET ou POST ; l’en-tête de réponse Allow |
415 Unsupported Media Type | Le serveur ne sait pas lire le format du corps | L’en-tête Content-Type |
422 Unprocessable Entity | JSON valide, mais la validation a échoué | La liste des erreurs de champs dans le corps de la réponse |
429 Too Many Requests | Limite de débit atteinte | L’en-tête Retry-After |
5xx | Le serveur a échoué | Les logs du serveur ; si une autre entrée fonctionne |
- L’en-tête est-il seulement présent ? Certains clients HTTP suppriment
Authorizationen 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 motBearerune seule fois. UnBearer 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 aussiaud(audience) etiss(é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.
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.
Comparez l’URL caractère par caractère avec la documentation de l’API :
- L’URL de base et la version de l’API (
/ouv1/ /).v2/ - Une barre oblique finale :
/etusers /sont des routes différentes sur beaucoup de serveurs.users/ - Des paramètres de chemin jamais substitués, comme
/ouusers/ undefined /.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.
Un corps JSON nécessite Content-Type: application/. 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.
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/ (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 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:/et/ localhost:3000 http:/sont des origines différentes./ localhost:5173 - La requête préalable
OPTIONSéchoue. Les requêtes avec un corps JSON ou un en-têteAuthorizationdéclenchent une requête préalable (preflight). Si le serveur y répond par401,404ou405(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 etAccess-Control-Allow-Credentials: true.Access-Control-Allow-Origin: *n’est pas autorisé. - Des erreurs sans en-têtes CORS. Si le serveur renvoie un
500sans 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.
- 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
localhostdepuis 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.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.apiTimeout
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.