Parcourir les aide-mémoire · API
Diagnostiquer les requêtes d’API
Diagnostiquez les requêtes d’API en échec ou lentes en isolant le DNS, le TLS, l’authentification, le routage, les limites de débit, les payloads, les passerelles, les erreurs applicatives, les nouvelles tentatives et les dépendances en aval.
Sur cette page
- Problème
- Réponse rapide
- Code / commandes
- 1. Reproduire en dehors de l’application
- 2. Recueillir séparément le statut, le corps et les en-têtes
- 3. Ajouter un identifiant de corrélation
- 4. Tester la méthode HTTP exacte
- 5. Envoyer le corps de requête exact
- 6. Vérifier le Content-Type de la requête
- 7. Vérifier Accept séparément
- 8. Diagnostiquer le temps de résolution DNS
- 9. Voir quelle adresse IP a été atteinte
- 10. Forcer la résolution DNS pour un test contrôlé
- 11. Vérifier le temps de connexion TCP
- 12. Vérifier le temps de négociation TLS
- 13. Inspecter les détails TLS
- 14. Ne pas utiliser --insecure comme correctif
- 15. Utiliser la bonne autorité de certification interne
- 16. Tester le mTLS lorsqu’il est exigé
- 17. Détecter l’influence d’un proxy
- 18. Contourner le proxy pour un hôte
- 19. Forcer l’utilisation d’un proxy pour comparer
- 20. Vérifier le comportement des redirections
- 21. Ne pas transmettre aveuglément les identifiants de connexion lors des redirections
- 22. Diagnostiquer l’authentification séparément
- 23. Distinguer 401 de 403
- 24. Vérifier l’autorisation sur le tenant/la ressource
- 25. Diagnostiquer un 404
- 26. Diagnostiquer un 405
- 27. Diagnostiquer un 409
- 28. Diagnostiquer un 412
- 29. Diagnostiquer un 415
- 30. Diagnostiquer un 422
- 31. Diagnostiquer un 429
- 32. Éviter les tempêtes de nouvelles tentatives
- 33. Réessayer uniquement lorsque la sémantique de l’opération le permet
- 34. Utiliser des clés d’idempotence pour les créations réessayables lorsqu’elles sont prises en charge
- 35. Diagnostiquer un 500
- 36. Diagnostiquer un 502
- 37. Diagnostiquer un 503
- 38. Diagnostiquer un 504
- 39. Identifier quelle couche a renvoyé l’erreur
- 40. Mesurer le temps jusqu’au premier octet
- 41. Mesurer la taille de la réponse
- 42. Vérifier la compression
- 43. Vérifier la pagination avant d’incriminer la latence
- 44. Reproduire une page précise
- 45. Garder des filtres identiques en comparant les pages
- 46. Valider la structure de la réponse JSON
- 47. Inspecter les en-têtes de la réponse indépendamment de l’analyse JSON
- 48. Vérifier l’encodage des caractères si le texte est corrompu
- 49. Vérifier la taille de la requête en cas de 413
- 50. Vérifier la taille des en-têtes en cas de 431
- 51. Tester CORS indépendamment de l’accessibilité de l’API
- 52. Si cURL fonctionne mais que le navigateur échoue
- 53. Si cela fonctionne en local mais échoue en CI
- 54. Si cela fonctionne en local mais échoue dans un conteneur
- 55. Si une seule région échoue
- 56. Si un seul client échoue
- 57. Si tous les clients échouent en même temps
- 58. Si les échecs commencent après un déploiement
- 59. Si les échecs sont intermittents
- 60. Repérer les schémas liés à l’expiration des jetons
- 61. Empêcher les ruées sur le renouvellement des jetons
- 62. Vérifier la synchronisation des horloges
- 63. Vérifier le comportement de réutilisation des connexions
- 64. Tester des requêtes répétées
- 65. Comparer les versions HTTP lorsque c’est pertinent
- 66. Inspecter la version HTTP négociée
- 67. Ne pas confondre délai d’expiration du client et du serveur
- 68. Aligner volontairement les budgets de délai d’expiration
- 69. Éviter de réessayer au-delà de l’échéance de l’appelant
- 70. Vérifier les dépendances en aval pour les requêtes lentes
- 71. Suivre séparément la durée de chaque dépendance
- 72. Vérifier le comportement des requêtes en base de données
- 73. Vérifier l’épuisement du pool de connexions
- 74. Vérifier la saturation des threads/de la boucle d’événements
- 75. Vérifier le coût de sérialisation des réponses très volumineuses
- 76. Vérifier les transformations effectuées par la passerelle
- 77. Vérifier le WAF/la stratégie de sécurité
- 78. Vérifier la mise en cache
- 79. Contourner le cache uniquement si l’API prend en charge une voie de diagnostic sûre
- 80. Comparer le comportement de l’ETag
- 81. Vérifier l’idempotence en cas d’échec d’écriture
- 82. Distinguer un échec de transport d’un échec HTTP
- 83. Vérifier le code de sortie de cURL
- 84. Ne pas masquer le corps de l’erreur dans l’automatisation
- 85. Consigner un enregistrement d’incident minimal
- 86. Comparer les requêtes qui fonctionnent et celles qui échouent
- 87. Reproduire avec la plus petite requête possible
- 88. Ne modifier qu’une variable à la fois
- 89. Ne pas désactiver les contrôles de sécurité pour faire passer le test
- 90. S’arrêter lorsque les éléments pointent en dehors de l’API
- Interpréter le résultat
- Points à vérifier
- Les échecs se concentrent sur un seul client
- Les échecs se concentrent sur une seule adresse IP de backend
- Les échecs commencent à l’expiration du jeton
- Le corps d’un 5xx est du HTML
- Les 429 augmentent après la première réponse de limitation
- TTFB élevé mais CPU de l’API sain
- API rapide en local, lente via la passerelle
- Dépassement de délai d’un POST suivi d’enregistrements en double
- Notes de production
- La qualité de la reproduction compte
- Protéger les secrets dans les diagnostics
- Délais d’expiration et nouvelles tentatives interagissent
- Les passerelles modifient la surface de diagnostic
- La supervision doit préserver la corrélation
- Une requête réussie ne prouve pas que tout est sain
- Erreurs fréquentes
- 1. Commencer par le code de l’application avant de vérifier le DNS/le TLS/le statut
- 2. Tester une requête différente de celle qui échoue
- 3. Considérer 401 et 403 comme interchangeables
- 4. Augmenter les délais d’expiration avant d’avoir trouvé la dépendance lente
- 5. Réessayer automatiquement chaque échec
- 6. Utiliser --insecure comme correctif TLS permanent
- 7. Partager des traces détaillées contenant des secrets
- 8. Supposer que chaque 5xx provient du code de l’application
- 9. Ne regarder que la latence moyenne
- 10. Modifier plusieurs choses à la fois
- Étape suivante
- Pour aller plus loin
Problème
Une requête d’API échoue, dépasse son délai d’expiration, renvoie un statut incorrect ou se comporte différemment d’un environnement à l’autre.
Toute la difficulté consiste à déterminer quelle couche est en échec :
client
→ DNS
→ réseau
→ TLS
→ proxy / passerelle / équilibreur de charge
→ authentification
→ routage
→ application
→ base de données / service en aval
L’objectif est de reproduire la plus petite requête en échec, de recueillir suffisamment d’éléments pour identifier la couche défaillante et d’éviter les modifications au hasard qui masquent le vrai problème.
Réponse rapide
Commencez par une requête reproductible :
curl \
--silent \
--show-error \
--location \
--dump-header headers.txt \
--output body.json \
--write-out \
"status=%{http_code} ip=%{remote_ip} dns=%{time_namelookup}s connect=%{time_connect}s tls=%{time_appconnect}s ttfb=%{time_starttransfer}s total=%{time_total}s\n" \
"https://api.example.com/v1/reports"
Classez ensuite l’échec :
Aucune connexion
→ DNS, routage, pare-feu, proxy, port
Échec TLS
→ nom d’hôte, chaîne de certificats, confiance, mTLS
401
→ authentification
403
→ autorisation / tenant / stratégie
404
→ route, version, ressource, mappage de la passerelle
409 / 412
→ conflit d’état ou de concurrence
415 / 422
→ type de contenu ou validation
429
→ limitation de débit / comportement des nouvelles tentatives
5xx
→ défaillance de l’application, de la passerelle ou d’une dépendance en aval
TTFB lent
→ traitement côté serveur ou dépendance
TTFB rapide, total lent
→ taille du payload / chemin de transfert
Recueillez toujours :
horodatage
identifiant de requête / de corrélation
méthode
URL
statut
en-têtes de la réponse
corps de la réponse non sensible
identité du client
temps de réponse
environnement
Ne consignez jamais d’identifiants de connexion dans des journaux partagés.
Code / commandes
1. Reproduire en dehors de l’application
Utilisez cURL pour distinguer le comportement du client applicatif de celui de l’API :
curl \
--verbose \
"https://api.example.com/v1/health"
Si cURL réussit mais que l’application échoue, comparez :
- l’URL
- la méthode
- les en-têtes
- l’authentification
- les paramètres de proxy
- la confiance TLS
- le délai d’expiration
- le corps de la requête
- la gestion des redirections
Ne supposez pas que le serveur est en cause tant que les deux requêtes ne sont pas équivalentes.
2. Recueillir séparément le statut, le corps et les en-têtes
curl \
--silent \
--show-error \
--dump-header headers.txt \
--output body.json \
--write-out "%{http_code}\n" \
"https://api.example.com/v1/reports"
C’est préférable à tout mélanger dans la sortie du terminal pendant l’analyse d’un incident.
3. Ajouter un identifiant de corrélation
REQUEST_ID="debug-$(date +%s)"
curl \
--header "X-Correlation-ID: $REQUEST_ID" \
"https://api.example.com/v1/reports"
Utilisez l’en-tête de corrélation documenté par l’API s’il en existe déjà un.
Le même identifiant doit apparaître dans la télémétrie de la passerelle/de l’application lorsque c’est possible.
4. Tester la méthode HTTP exacte
curl \
--request POST \
"https://api.example.com/v1/reports"
Ne testez pas un endpoint POST en échec avec GET pour conclure ensuite que la route est saine.
Des méthodes différentes peuvent utiliser des éléments différents :
- autorisation
- routage
- analyse du corps
- logique du backend
5. Envoyer le corps de requête exact
curl \
--request POST \
--header "Content-Type: application/json" \
--data @payload.json \
"https://api.example.com/v1/reports"
Utilisez un payload enregistré lorsque vous reproduisez un problème de production.
Expurgez les champs sensibles avant de le partager.
6. Vérifier le Content-Type de la requête
Pour du JSON :
curl \
--header "Content-Type: application/json" \
--data @payload.json \
"https://api.example.com/v1/reports"
Si le serveur renvoie 415, vérifiez l’en-tête qui atteint réellement le service.
Un proxy ou une bibliothèque cliente peut le modifier.
7. Vérifier Accept séparément
curl \
--header "Accept: application/json" \
"https://api.example.com/v1/reports"
À retenir :
Content-Type
→ format du corps de la requête
Accept
→ format de réponse préféré
8. Diagnostiquer le temps de résolution DNS
curl \
--silent \
--output /dev/null \
--write-out "dns=%{time_namelookup}s\n" \
"https://api.example.com/health"
Si le temps DNS est anormalement élevé par rapport à la normale pour le même environnement, examinez :
- le résolveur
- le VPN
- le DNS d’entreprise
- le DNS fractionné (split DNS)
- le DNS du conteneur
- le DNS du VNet/VPC
Ne posez pas de diagnostic à partir d’un seul échantillon.
9. Voir quelle adresse IP a été atteinte
curl \
--silent \
--output /dev/null \
--write-out "remote_ip=%{remote_ip}\n" \
"https://api.example.com/health"
Utile lorsque :
- le DNS renvoie plusieurs adresses
- le trafic est routé par région
- un chemin d’équilibreur de charge/de backend n’est pas sain
10. Forcer la résolution DNS pour un test contrôlé
curl \
--resolve api.example.com:443:203.0.113.10 \
"https://api.example.com/health"
Cela conserve le nom d’hôte pour le TLS/SNI tout en se connectant à l’adresse IP indiquée.
À n’utiliser que si vous savez que l’adresse IP cible est valide.
11. Vérifier le temps de connexion TCP
curl \
--silent \
--output /dev/null \
--write-out "connect=%{time_connect}s\n" \
"https://api.example.com/health"
Un temps de connexion long peut indiquer :
- le chemin réseau
- un pare-feu
- un équilibreur de charge surchargé
- une perte de paquets
- un chemin de backend injoignable
12. Vérifier le temps de négociation TLS
curl \
--silent \
--output /dev/null \
--write-out "tls=%{time_appconnect}s\n" \
"https://api.example.com/health"
Pour HTTPS, comparez :
time_connect
et
time_appconnect
Un écart important peut indiquer un retard de négociation TLS.
13. Inspecter les détails TLS
curl \
--verbose \
"https://api.example.com/health"
Recherchez :
- le sujet/SAN du certificat
- l’émetteur
- la vérification du certificat
- la négociation TLS
- une incohérence SNI/nom d’hôte
- les exigences de certificat client
La sortie détaillée peut exposer des en-têtes et des jetons. Masquez-les avant de la partager.
14. Ne pas utiliser --insecure comme correctif
Exemple réservé au diagnostic :
curl \
--insecure \
"https://api.example.com/health"
Si cela fonctionne alors que la vérification normale échoue, examinez :
- la chaîne de confiance
- le nom d’hôte
- l’autorité de certification interne
- l’expiration du certificat
- le magasin de certificats de confiance du système
Ne laissez pas la validation des certificats désactivée dans les clients de production.
15. Utiliser la bonne autorité de certification interne
curl \
--cacert company-root-ca.pem \
"https://internal-api.example.com/health"
Cela conserve la vérification TLS.
16. Tester le mTLS lorsqu’il est exigé
curl \
--cert client-cert.pem \
--key client-key.pem \
"https://api.example.com/v1/data"
Si le mTLS échoue, examinez à la fois :
- la validation du certificat serveur
- l’acceptation du certificat client
17. Détecter l’influence d’un proxy
Vérifiez l’environnement :
env | grep -i proxy
Variables courantes :
HTTP_PROXY
HTTPS_PROXY
NO_PROXY
Une requête peut se comporter différemment selon qu’elle s’exécute dans :
- un ordinateur portable
- la CI
- un conteneur
- une VM
- un pod Kubernetes
car la configuration du proxy diffère.
18. Contourner le proxy pour un hôte
curl \
--noproxy "api.example.com" \
"https://api.example.com/health"
Si l’accès direct fonctionne mais que l’accès via le proxy échoue, examinez la stratégie/le routage du proxy.
19. Forcer l’utilisation d’un proxy pour comparer
curl \
--proxy "http://proxy.example.com:8080" \
"https://api.example.com/health"
À n’utiliser que si ce proxy est approuvé pour l’environnement.
20. Vérifier le comportement des redirections
curl \
--include \
"https://api.example.com/v1/reports"
Puis suivez-les :
curl \
--location \
--include \
"https://api.example.com/v1/reports"
Les redirections peuvent masquer :
- des passages de HTTP à HTTPS
- des pages de connexion
- des chemins de base incorrects
- des réécritures par la passerelle
- des changements de région
21. Ne pas transmettre aveuglément les identifiants de connexion lors des redirections
Inspectez d’abord la cible de la redirection.
Les identifiants de connexion ne doivent pas être transmis à un hôte sans rapport.
22. Diagnostiquer l’authentification séparément
Requête avec un jeton Bearer :
curl \
--header "Authorization: Bearer $ACCESS_TOKEN" \
"https://api.example.com/v1/reports"
Si la réponse est 401, vérifiez :
- la présence du jeton
- l’expiration
- l’émetteur
- l’audience
- la signature
- le type de jeton
- l’horloge du client
Ne journalisez pas le jeton lui-même.
23. Distinguer 401 de 403
Interprétation habituelle :
401
→ authentification manquante ou invalide
403
→ identité acceptée mais action non autorisée
Pour un 403, examinez :
- le scope
- le rôle
- le tenant
- la propriété de la ressource
- la stratégie réseau/d’accès
24. Vérifier l’autorisation sur le tenant/la ressource
Pour les API multi-tenant :
le tenant authentifié
doit correspondre
au tenant de la ressource
Un jeton valide ne prouve pas à lui seul l’accès à la ressource demandée.
25. Diagnostiquer un 404
Vérifiez :
URL de base
route
méthode HTTP
version de l’API
identifiant de la ressource
route de la passerelle
mappage du tenant
Un 404 peut être généré par :
- la passerelle d’API
- le routeur de l’application
- la recherche de ressource dans l’application
Identifiez quelle couche a répondu.
26. Diagnostiquer un 405
Si vous obtenez :
405 Method Not Allowed
inspectez l’en-tête Allow lorsqu’il est présent.
La route existe peut-être mais rejette la méthode.
27. Diagnostiquer un 409
Causes typiques :
- conflit de concurrence optimiste
- clé unique en double
- transition d’état invalide
- opération déjà terminée
Ne réessayez pas automatiquement sans comprendre la sémantique du conflit.
28. Diagnostiquer un 412
Un 412 Precondition Failed signifie souvent qu’une requête conditionnelle a échoué.
Exemple :
If-Match: "old-etag"
La ressource a changé après sa lecture par le client.
Rechargez la ressource avant de décider s’il faut réessayer.
29. Diagnostiquer un 415
Vérifiez :
Content-Type
encodage du corps
délimiteur multipart (boundary)
sérialiseur du client
transformation par la passerelle
Ne supposez pas que le corps JSON est valide simplement parce que l’objet client a été sérialisé localement.
30. Diagnostiquer un 422
Examinez la validation sémantique :
- combinaisons obligatoires
- relations entre les dates
- règles métier
- valeurs d’énumération
- état de la ressource
La requête peut être syntaxiquement valide mais logiquement inacceptable.
31. Diagnostiquer un 429
Inspectez les en-têtes de la réponse :
curl \
--include \
"https://api.example.com/v1/data"
Recherchez :
Retry-After
RateLimit-*
X-RateLimit-*
Examinez ensuite :
- les requêtes par client
- la concurrence
- les nouvelles tentatives
- la taille des lots/des pages
- un appelant particulièrement bruyant
32. Éviter les tempêtes de nouvelles tentatives
Mauvaise pratique :
429
→ nouvelle tentative immédiate
→ 429
→ nouvelle tentative immédiate
Préférez un backoff borné et respectez Retry-After.
33. Réessayer uniquement lorsque la sémantique de l’opération le permet
Statuts potentiellement transitoires :
429
502
503
504
peuvent justifier une nouvelle tentative.
Mais la sécurité dépend :
- de l’idempotence
- de la méthode
- du fait que le serveur a peut-être déjà validé le travail
- des recommandations du fournisseur
Ne réessayez pas aveuglément les POST/PATCH/DELETE.
34. Utiliser des clés d’idempotence pour les créations réessayables lorsqu’elles sont prises en charge
curl \
--request POST \
--header "Idempotency-Key: $REQUEST_ID" \
--header "Content-Type: application/json" \
--data @payload.json \
"https://api.example.com/v1/payments"
Cela ne fonctionne que si le serveur implémente une sémantique d’idempotence.
35. Diagnostiquer un 500
Un 500 indique une défaillance inattendue côté serveur.
Recueillez :
identifiant de requête
horodatage
route
métadonnées de requête non sensibles
identité de l’appelant
Corrélez-les ensuite avec les journaux du serveur.
N’exposez pas de traces de pile (stack traces) à l’appelant.
36. Diagnostiquer un 502
Chemin typique :
client
→ passerelle
→ backend
Un 502 signifie souvent que la passerelle a reçu une réponse invalide/en échec de l’amont.
Vérifiez :
- l’état de santé du backend
- les réinitialisations de connexion
- le TLS en amont
- le protocole de la réponse
- les journaux du proxy/de la passerelle
37. Diagnostiquer un 503
Vérifiez :
- l’état du déploiement
- le nombre de backends sains
- la surcharge
- la maintenance
- la disponibilité des dépendances
- le délestage de charge (load shedding)
Si Retry-After est présent, respectez-le.
38. Diagnostiquer un 504
Un 504 signifie généralement qu’une passerelle/un proxy a dépassé son délai en attendant un service en amont.
Vérifiez :
délai d’expiration de la passerelle
durée de l’application
durée de la base de données
durée de l’API en aval
mise en file d’attente
Augmenter le délai d’expiration n’est pas automatiquement la solution.
39. Identifier quelle couche a renvoyé l’erreur
Inspectez :
curl \
--include \
"https://api.example.com/v1/reports"
Indices utiles :
Server
Via
X-Request-ID
X-Correlation-ID
en-têtes propres à la passerelle
Content-Type
format du corps
Une page d’erreur HTML renvoyée par une API JSON indique souvent un intermédiaire.
40. Mesurer le temps jusqu’au premier octet
curl \
--silent \
--output /dev/null \
--write-out "ttfb=%{time_starttransfer}s total=%{time_total}s\n" \
"https://api.example.com/v1/reports"
Interprétation :
TTFB élevé
→ retard de traitement du serveur/de la passerelle/d’une dépendance
TTFB faible mais total élevé
→ réponse volumineuse ou transfert lent
41. Mesurer la taille de la réponse
curl \
--silent \
--output /dev/null \
--write-out "bytes=%{size_download}\n" \
"https://api.example.com/v1/reports"
Des payloads volumineux peuvent expliquer un temps total long même lorsque la réponse du serveur commence rapidement.
42. Vérifier la compression
curl \
--compressed \
"https://api.example.com/v1/reports"
Pour les réponses JSON volumineuses, la compression peut réduire sensiblement la taille du transfert.
43. Vérifier la pagination avant d’incriminer la latence
Si l’endpoint renvoie un jeu de données énorme, vérifiez si l’appelant :
- demande une taille de page excessive
- parcourt des offsets profonds
- récupère des champs inutiles
- ignore la pagination
Le problème peut venir de l’utilisation de l’API plutôt que de la seule exécution côté serveur.
44. Reproduire une page précise
Exemple :
curl \
"https://api.example.com/v1/orders?limit=100&offset=10000"
ou :
curl \
"https://api.example.com/v1/orders?limit=100&after=$CURSOR"
Comparez les premières pages aux pages suivantes.
La lenteur liée aux offsets profonds peut venir de la requête en base.
45. Garder des filtres identiques en comparant les pages
Modifier les filtres ou le tri invalide la comparaison.
Utilisez exactement les mêmes :
- filtres
- ordre
- tenant
- identité d’authentification
46. Valider la structure de la réponse JSON
Avec jq :
curl \
--silent \
"https://api.example.com/v1/reports" \
| jq .
Si l’analyse échoue, inspectez la réponse brute.
Vous avez peut-être reçu :
- du HTML
- un corps vide
- du JSON tronqué
- une erreur de proxy
47. Inspecter les en-têtes de la réponse indépendamment de l’analyse JSON
curl \
--dump-header headers.txt \
--output body.json \
"https://api.example.com/v1/reports"
Ne laissez pas un analyseur JSON masquer la réponse HTTP réelle.
48. Vérifier l’encodage des caractères si le texte est corrompu
Inspectez :
Content-Type: application/json; charset=utf-8
ainsi que les octets réels.
Les problèmes d’encodage sont distincts des erreurs métier de l’API.
49. Vérifier la taille de la requête en cas de 413
Si la réponse est :
413 Content Too Large
examinez les limites au niveau :
- du CDN
- du WAF
- de l’équilibreur de charge
- de la passerelle
- du serveur web
- de l’application
L’application peut ne jamais recevoir la requête.
50. Vérifier la taille des en-têtes en cas de 431
Causes courantes :
- cookies surdimensionnés
- JWT volumineux
- en-têtes de traçage répétés
- accumulation d’en-têtes par les proxys
Là encore, un intermédiaire peut rejeter la requête avant l’application.
51. Tester CORS indépendamment de l’accessibilité de l’API
Requête preflight manuelle :
curl \
--request OPTIONS \
--header "Origin: https://app.example.com" \
--header "Access-Control-Request-Method: POST" \
--header "Access-Control-Request-Headers: authorization,content-type" \
--include \
"https://api.example.com/v1/reports"
À retenir :
le navigateur bloque à cause de CORS
!=
l’API est injoignable
cURL n’applique pas la stratégie CORS des navigateurs.
52. Si cURL fonctionne mais que le navigateur échoue
Examinez :
- les en-têtes CORS
- la requête preflight
- les règles SameSite des cookies
- le contenu mixte
- la stratégie d’identifiants du navigateur
Ne commencez pas par déboguer la connexion au backend si les appels bruts à l’API réussissent.
53. Si cela fonctionne en local mais échoue en CI
Comparez :
DNS
proxy
certificats d’autorité
disponibilité des secrets
identité du service
pare-feu
règles de sortie (egress)
variables d’environnement
La CI dispose souvent d’un environnement réseau et de confiance différent.
54. Si cela fonctionne en local mais échoue dans un conteneur
Vérifiez depuis l’intérieur du conteneur :
curl \
--verbose \
"https://api.example.com/health"
Examinez :
- le DNS
- le bundle d’autorités de certification
- les variables d’environnement du proxy
- l’espace de noms réseau
- la découverte de services
- les secrets montés
55. Si une seule région échoue
Comparez :
- l’adresse IP distante
- la réponse DNS
- la région de la passerelle
- le pool de backends
- la version déployée
- l’état de santé des dépendances régionales
Ne supposez pas qu’une API mondiale emprunte un chemin réseau unique et identique.
56. Si un seul client échoue
Comparez sa requête exacte avec celle d’un client dont le fonctionnement est avéré.
Recherchez :
- un jeton différent
- une URL de base incorrecte
- une version d’API obsolète
- un proxy personnalisé
- un délai d’expiration différent
- des différences dans le corps de la requête
57. Si tous les clients échouent en même temps
Priorisez les composants partagés :
DNS
passerelle
fournisseur d’identité
déploiement du backend
base de données
dépendance en aval partagée
Un bug simultané côté clients est moins probable, sauf si un déploiement ou une configuration partagés ont changé.
58. Si les échecs commencent après un déploiement
Comparez :
- la version déployée
- la configuration des routes
- les variables d’environnement
- les paramètres d’authentification
- les modifications de schéma
- les versions des dépendances
- la stratégie de la passerelle
Ne revenez en arrière (rollback) que si les éléments recueillis le justifient.
59. Si les échecs sont intermittents
Recueillez pour chaque requête :
identifiant de requête
horodatage
adresse IP distante
statut
latence
instance de backend
nombre de nouvelles tentatives
Les échecs intermittents sont souvent corrélés à un(e) seul(e) :
- instance
- région
- dépendance
- pool de connexions
- cycle de renouvellement des identifiants
60. Repérer les schémas liés à l’expiration des jetons
Si les échecs surviennent à intervalle régulier :
toutes les 60 minutes
toutes les 24 heures
examinez :
- l’expiration du jeton d’accès
- la logique de renouvellement
- l’invalidation du cache
- la rotation des certificats/jetons
61. Empêcher les ruées sur le renouvellement des jetons
Dans les clients à forte concurrence, plusieurs workers peuvent tous renouveler un jeton sur le point d’expirer.
Utilisez un mécanisme single-flight/de verrouillage ou un cache de jetons partagé.
Une rafale de requêtes d’authentification peut provoquer des échecs 401/429 intermittents.
62. Vérifier la synchronisation des horloges
La validation des jetons et le TLS peuvent échouer si l’heure système est incorrecte.
Inspectez l’horloge de l’hôte/du conteneur lorsque vous observez :
- un jeton pas encore valide
- un jeton expiré de manière inattendue
- des anomalies de validité des certificats
63. Vérifier le comportement de réutilisation des connexions
Un client qui utilise des connexions HTTP mises en pool peut se comporter différemment de la requête ponctuelle de cURL.
Examinez :
- les connexions obsolètes dans le pool
- les changements DNS
- le délai d’inactivité
- le keep-alive du proxy
- la durée de vie des connexions sur l’équilibreur de charge
64. Tester des requêtes répétées
for i in 1 2 3 4 5; do
curl \
--silent \
--output /dev/null \
--write-out \
"status=%{http_code} ip=%{remote_ip} total=%{time_total}s\n" \
"https://api.example.com/health"
done
Cela peut révéler un comportement intermittent lié à un backend/une adresse IP.
Ne transformez pas un diagnostic en production en test de charge.
65. Comparer les versions HTTP lorsque c’est pertinent
curl \
--http1.1 \
"https://api.example.com/health"
et :
curl \
--http2 \
"https://api.example.com/health"
À n’utiliser que si les éléments recueillis suggèrent des différences au niveau du protocole.
66. Inspecter la version HTTP négociée
curl \
--silent \
--output /dev/null \
--write-out "%{http_version}\n" \
"https://api.example.com/health"
67. Ne pas confondre délai d’expiration du client et du serveur
Points de défaillance possibles :
délai d’expiration du client
délai d’expiration de la passerelle
délai d’expiration de l’application
délai d’expiration de la base de données
délai d’expiration de l’API en aval
Identifiez à quel endroit le dépassement de délai est généré.
68. Aligner volontairement les budgets de délai d’expiration
Sur le plan conceptuel :
délai d’expiration du client
>
délai d’expiration de la passerelle
>
délai d’expiration des appels en aval de l’application
peut être utile pour que les défaillances en aval remontent avant que les appelants externes n’abandonnent, mais les valeurs réelles dépendent de l’architecture.
Ne copiez pas de valeurs de délai universelles.
69. Éviter de réessayer au-delà de l’échéance de l’appelant
Les nouvelles tentatives doivent tenir dans le budget global de la requête.
Un client qui réessaie trois fois avec de longs délais d’expiration peut largement dépasser la latence attendue par l’utilisateur.
70. Vérifier les dépendances en aval pour les requêtes lentes
Si le TTFB est élevé, examinez :
- la base de données
- le cache
- le broker de messages
- les API en aval
- les appels au fournisseur d’identité
- le système de fichiers/le stockage objet
L’endpoint n’est peut-être que la partie visible d’une chaîne de dépendances plus longue.
71. Suivre séparément la durée de chaque dépendance
Une bonne télémétrie côté serveur enregistre :
durée totale de la requête
durée de la base de données
durée de l’API en aval
durée de mise en file d’attente
durée de sérialisation
Sans cette ventilation, « l’API a mis 8 secondes » n’est pas exploitable.
72. Vérifier le comportement des requêtes en base de données
Si la latence de l’API correspond à des appels à la base de données, examinez :
- les blocages
- les requêtes de longue durée
- la consommation CPU élevée
- les lectures élevées
- les index manquants/inefficaces
- la sensibilité aux paramètres
- l’épuisement du pool de connexions
N’augmentez pas aveuglément le nombre d’instances de l’API pour résoudre un goulot d’étranglement de la base de données.
73. Vérifier l’épuisement du pool de connexions
Les symptômes peuvent inclure :
- des dépassements de délai intermittents
- une mise en file d’attente accrue
- un CPU du backend faible malgré des réponses lentes
- des échecs sous forte concurrence
Examinez les métriques du pool plutôt que les seuls journaux de l’endpoint.
74. Vérifier la saturation des threads/de la boucle d’événements
Les symptômes côté application peuvent inclure :
- des réponses lentes malgré des dépendances en aval saines
- la croissance de la file d’attente des requêtes
- une concurrence en hausse
- du travail synchrone bloquant
Utilisez la télémétrie propre au runtime.
Ne posez pas ce diagnostic à partir du seul statut HTTP.
75. Vérifier le coût de sérialisation des réponses très volumineuses
Les réponses JSON imbriquées volumineuses peuvent passer un temps significatif dans :
- la matérialisation des objets
- la sérialisation
- la compression
- le transfert réseau
Réduisez la structure du payload avant de simplement ajouter de la puissance de calcul.
76. Vérifier les transformations effectuées par la passerelle
Les passerelles peuvent :
- réécrire les chemins
- ajouter/supprimer des en-têtes
- valider les jetons
- limiter le débit
- transformer les corps
- mettre en cache
- terminer le TLS
Comparez le comportement des requêtes/réponses avant et après la passerelle lorsque l’architecture le permet.
77. Vérifier le WAF/la stratégie de sécurité
Des 403 inattendus ou des requêtes bloquées peuvent provenir :
- d’une règle WAF
- d’une restriction d’adresse IP
- d’une restriction géographique
- d’une protection contre les bots
- d’une stratégie de taille de requête
- d’une règle de détection de schémas suspects
Identifiez la couche qui répond avant de modifier l’autorisation de l’application.
78. Vérifier la mise en cache
Une réponse obsolète ou incohérente peut provenir :
- du CDN
- du proxy inverse
- de la passerelle d’API
- du cache de l’application
Inspectez :
Cache-Control
Age
ETag
Last-Modified
Via
X-Cache
lorsqu’ils sont disponibles.
79. Contourner le cache uniquement si l’API prend en charge une voie de diagnostic sûre
N’inventez pas d’en-têtes tels que :
X-Bypass-Cache: true
sauf si la plateforme les prend explicitement en charge.
Utilisez les contrôles de cache documentés.
80. Comparer le comportement de l’ETag
Requête :
curl \
--include \
"https://api.example.com/v1/config"
Puis :
curl \
--header 'If-None-Match: "abc123"' \
--include \
"https://api.example.com/v1/config"
Utile pour déboguer le comportement d’un client qui conserve des données obsolètes.
81. Vérifier l’idempotence en cas d’échec d’écriture
Scénario :
le POST dépasse son délai
État inconnu :
Le serveur a-t-il validé l’opération avant l’échec de la connexion ?
Ne réessayez pas aveuglément, sauf si l’endpoint prend en charge l’idempotence ou si vous pouvez interroger l’état de l’opération en toute sécurité.
82. Distinguer un échec de transport d’un échec HTTP
Exemples :
échec DNS
échec TLS
réinitialisation de la connexion
délai dépassé avant la réponse HTTP
peuvent ne produire aucun statut HTTP.
Votre client doit enregistrer les deux :
erreur de transport
statut HTTP s’il existe
83. Vérifier le code de sortie de cURL
curl \
--fail-with-body \
--silent \
--show-error \
"https://api.example.com/v1/data"
echo $?
Un code de sortie cURL non nul n’est pas la même chose qu’un code de statut HTTP.
84. Ne pas masquer le corps de l’erreur dans l’automatisation
Préférez :
curl \
--fail-with-body \
--silent \
--show-error \
"https://api.example.com/v1/data"
à un simple --fail lorsque le corps contient des diagnostics utiles.
85. Consigner un enregistrement d’incident minimal
Modèle utile :
Horodatage UTC :
Environnement :
Méthode :
URL/chemin :
Appelant/client :
Identifiant de requête :
Statut HTTP :
Erreur de transport :
Adresse IP distante :
Temps DNS :
Temps de connexion :
Temps TLS :
TTFB :
Temps total :
Content-Type de la réponse :
Code/message d’erreur non sensible :
Nouvelle tentative effectuée :
N’incluez aucun secret.
86. Comparer les requêtes qui fonctionnent et celles qui échouent
Établissez une comparaison côte à côte des éléments suivants :
méthode
URL
chaîne de requête
en-têtes
identité d’authentification
payload
statut
temps de réponse
adresse IP distante
environnement
Les différences révèlent souvent le problème plus vite que la lecture isolée des journaux.
87. Reproduire avec la plus petite requête possible
Retirez les éléments facultatifs :
- en-têtes
- paramètres de requête
- champs du payload
- surcouches du client
jusqu’à ce que l’échec disparaisse.
Rajoutez-les ensuite un par un.
Cela isole le déclencheur.
88. Ne modifier qu’une variable à la fois
Mauvaise méthode de diagnostic :
modifier le délai d’expiration
modifier le proxy
modifier le jeton
modifier la route
redéployer
le tout en même temps.
Vous perdez le lien de causalité.
Préférez une modification contrôlée unique, avec des éléments avant/après.
89. Ne pas désactiver les contrôles de sécurité pour faire passer le test
Évitez d’utiliser comme correctifs permanents :
--insecure
authentification désactivée
pare-feu ouvert
WAF désactivé
limite de débit illimitée
Si l’une de ces modifications permet d’isoler la couche en échec, rétablissez le contrôle et corrigez la configuration réelle.
90. S’arrêter lorsque les éléments pointent en dehors de l’API
Si :
le DNS échoue
l’étape suivante ne concerne pas le code de l’application.
Si :
504 de la passerelle avec une dépendance de base de données lente
l’étape suivante n’est pas de modifier le gestionnaire de statuts HTTP.
Suivez les éléments recueillis jusqu’à la couche responsable.
Interpréter le résultat
| Signal | Couche probable |
|---|---|
| Échec DNS / temps DNS élevé | Configuration DNS / réseau |
| Connexion refusée | Endpoint, port, pare-feu, listener |
| Échec de vérification TLS | Certificat / confiance / nom d’hôte |
401 |
Authentification |
403 |
Autorisation, tenant, WAF/stratégie |
404 |
Route, version, ressource, mappage de la passerelle |
409 / 412 |
État ou concurrence |
415 / 422 |
Format de la requête ou validation sémantique |
429 |
Limitation de débit / profil de requêtes du client |
500 |
Défaillance de l’application |
502 |
Échec entre la passerelle et l’amont |
503 |
Disponibilité / surcharge / maintenance |
504 |
Délai dépassé en amont |
| TTFB élevé | Traitement par le serveur/la passerelle/une dépendance |
| Total élevé, TTFB faible | Taille du transfert / débit réseau |
| cURL fonctionne, l’application échoue | Différence de comportement/de configuration du client |
| Une seule région/instance échoue | Chemin régional/instance de backend |
Le meilleur modèle de diagnostic est :
transport
→ sécurité
→ routage
→ application
→ dépendances
Points à vérifier
Les échecs se concentrent sur un seul client
Examinez les éléments propres au client :
- identifiants de connexion
- proxy
- version du SDK
- forme de la requête
- boucle de nouvelles tentatives
- tenant
Les échecs se concentrent sur une seule adresse IP de backend
Soupçonnez une instance non saine ou un chemin régional défaillant.
Les échecs commencent à l’expiration du jeton
Examinez le renouvellement et la mise en cache des jetons.
Le corps d’un 5xx est du HTML
Il s’agit probablement d’une réponse de la passerelle/du proxy/d’un intermédiaire plutôt que du JSON de l’application.
Les 429 augmentent après la première réponse de limitation
Les nouvelles tentatives des clients amplifient peut-être la charge.
TTFB élevé mais CPU de l’API sain
Examinez les dépendances en aval, la mise en file d’attente, les pools de connexions et les blocages.
API rapide en local, lente via la passerelle
Examinez le chemin passerelle/WAF/proxy ainsi que les différences TLS/réseau.
Dépassement de délai d’un POST suivi d’enregistrements en double
Le client a probablement réessayé une opération non idempotente sans mécanisme d’idempotence sûr.
Notes de production
La qualité de la reproduction compte
Une bonne reproduction utilise les mêmes :
- environnement
- méthode
- en-têtes
- identité
- payload
- route
que la requête en échec.
Une requête simplifiée qui modifie ces dimensions risque de tester autre chose.
Protéger les secrets dans les diagnostics
Ne placez jamais en clair :
- de jetons d’accès
- de clés d’API
- de cookies
- de mots de passe
- de secrets client
- de clés privées
dans des tickets ou des journaux partagés.
Délais d’expiration et nouvelles tentatives interagissent
Un délai d’expiration long combiné à plusieurs nouvelles tentatives peut produire des échecs très longs pour l’utilisateur et des effets de bord en double.
Concevez-les ensemble.
Les passerelles modifient la surface de diagnostic
En production, l’API visible de l’extérieur comprend souvent plusieurs couches avant l’application.
Recueillez de la télémétrie à chaque frontière pertinente.
La supervision doit préserver la corrélation
Un identifiant de requête qui traverse :
client
→ passerelle
→ API
→ service en aval
est bien plus utile que des lignes de journal sans lien entre elles.
Une requête réussie ne prouve pas que tout est sain
Les problèmes intermittents nécessitent plusieurs échantillons horodatés, avec l’identité du backend/de la région lorsque c’est possible.
Erreurs fréquentes
1. Commencer par le code de l’application avant de vérifier le DNS/le TLS/le statut
Vous risquez de déboguer la mauvaise couche.
2. Tester une requête différente de celle qui échoue
Modifier la méthode, l’authentification, le payload ou l’environnement invalide la comparaison.
3. Considérer 401 et 403 comme interchangeables
Ils pointent vers des zones différentes.
4. Augmenter les délais d’expiration avant d’avoir trouvé la dépendance lente
Cela peut masquer le symptôme et dégrader la capacité.
5. Réessayer automatiquement chaque échec
Les nouvelles tentatives peuvent dupliquer des écritures ou provoquer des tempêtes de charge.
6. Utiliser --insecure comme correctif TLS permanent
Cette option désactive la vérification des certificats.
7. Partager des traces détaillées contenant des secrets
Les traces cURL peuvent exposer des éléments d’authentification.
8. Supposer que chaque 5xx provient du code de l’application
Les passerelles et les proxys génèrent aussi des erreurs.
9. Ne regarder que la latence moyenne
Les échecs intermittents peuvent toucher une seule région, une seule instance ou une seule dépendance.
10. Modifier plusieurs choses à la fois
Vous perdez les éléments nécessaires pour identifier la cause racine.
Ce contenu vous a-t-il été utile ?
Que pourrions-nous améliorer ?
Merci — cela m’aide à améliorer Javi Builds.
Restez au courant
Recevez uniquement les nouvelles de Javi Builds qui vous intéressent.
Consultez votre boîte de réception
Je vous ai envoyé un lien de confirmation. Votre abonnement sera actif après confirmation.