Quand ça part en vrille
Diagnostiquer les erreurs d'API comme un dev, pas en devinant au hasard
⏱ Estim. ~6 min
01 · Lire
Les API tombent. Les serveurs plantent. Les clés expirent. Les rate limits se déclenchent. Les URL contiennent des fautes de frappe.
La différence entre un débutant et un dev, ce n'est pas que ça ne casse pas — c'est la vitesse à laquelle tu diagnostiques et tu corriges.
L'approche systématique :
1. Lis le status code — quelle classe d'erreur ? 2. Lis le corps de la réponse — le serveur t'explique en général précisément le souci 3. Regarde les headers — Retry-After, WWW-Authenticate, X-RateLimit-* sont des mines d'or 4. Vérifie l'URL — une seule faute de frappe casse tout
Points clés
- Pour debugger, utilise toujours curl -i — tu as besoin de voir les headers
- Le corps de l'erreur est souvent plus utile que le status code seul
- 4xx = ton problème. 5xx = leur problème.
- Quand plus rien ne marche, va voir la status page du fournisseur d'API
02 · Exemple de code
Checklist de diagnostic par classe de status code.
4xx — erreur client (tu as fait une erreur)
400 Bad Request
→ Check: Is your JSON valid? Are required fields present?
→ Fix: Validate your -d body. Check the API docs for required fields.
401 Unauthorized
→ Check: Did you include the Authorization header? Is the key correct?
→ Fix: Check your API key. Make sure you're using the right header format.
403 Forbidden
→ Check: Do you have permission? Is this feature on your plan?
→ Fix: Check your account permissions or upgrade your plan.
404 Not Found
→ Check: Does the URL path exist? Did you replace all {placeholders}?
→ Fix: Double-check the URL against the docs. Check the resource ID.
429 Too Many Requests
→ Check: Look for Retry-After header — it tells you when to retry.
→ Fix: Slow down. Implement exponential backoff. Use caching.
5xx — erreur serveur (leur problème)
500 Internal Server Error
→ Their code crashed. Check their status page.
→ Retry after a brief wait.
503 Service Unavailable
→ Server is overloaded or in maintenance.
→ Check their status page. Wait and retry.
504 Gateway Timeout
→ Your request took too long. The server gave up.
→ Try again. If persistent, contact the API provider.
Erreurs curl (la réponse n'est même pas arrivée)
curl: (6) Could not resolve host
→ DNS failure. Check the hostname for typos.
→ Verify your internet connection.
curl: (7) Failed to connect
→ Server unreachable or port blocked.
→ Check if the service is down.
curl: (35) SSL certificate problem
→ Certificate expired or invalid.
→ Check if you're using https:// correctly.
03 · Pratique réelle
Envoie une requête sur un repo GitHub inexistant pour déclencher un vrai 404.
curl -i https://api.github.com/repos/this-user-doesnt-exist-xyz/no-such-repo
04 · Pratique réelle
Envoie une requête non authentifiée à un endpoint qui exige une authentification, pour déclencher un vrai 401.
curl -i https://api.github.com/user
05 · Quiz
Tu appelles une API et tu reçois un status code 429. Que faut-il faire ?
- Vérifier ton API key
- Changer d'URL
- Passer à une requête POST
- Attendre un peu et réessayer — tu as atteint le rate limit
06 · Compléter
Les status codes qui commencent par 4 indiquent que l'erreur vient du côté _____ (ta requête est mauvaise).
Autres leçons de ce chapitre
⚠ L'expérience interactive complète nécessite JavaScript. Active-le et recharge la page.
※ Ce site est un projet éducatif indépendant — pas un produit officiel d'Anthropic. Claude™ est une marque déposée d'Anthropic, PBC.