Parcourir les aide-mémoire · API

Technologie: APICatégorie: DépannageNiveau: IntermédiaireMis à jour

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
  1. Problème
  2. Réponse rapide
  3. Code / commandes
  4. 1. Reproduire en dehors de l’application
  5. 2. Recueillir séparément le statut, le corps et les en-têtes
  6. 3. Ajouter un identifiant de corrélation
  7. 4. Tester la méthode HTTP exacte
  8. 5. Envoyer le corps de requête exact
  9. 6. Vérifier le Content-Type de la requête
  10. 7. Vérifier Accept séparément
  11. 8. Diagnostiquer le temps de résolution DNS
  12. 9. Voir quelle adresse IP a été atteinte
  13. 10. Forcer la résolution DNS pour un test contrôlé
  14. 11. Vérifier le temps de connexion TCP
  15. 12. Vérifier le temps de négociation TLS
  16. 13. Inspecter les détails TLS
  17. 14. Ne pas utiliser --insecure comme correctif
  18. 15. Utiliser la bonne autorité de certification interne
  19. 16. Tester le mTLS lorsqu’il est exigé
  20. 17. Détecter l’influence d’un proxy
  21. 18. Contourner le proxy pour un hôte
  22. 19. Forcer l’utilisation d’un proxy pour comparer
  23. 20. Vérifier le comportement des redirections
  24. 21. Ne pas transmettre aveuglément les identifiants de connexion lors des redirections
  25. 22. Diagnostiquer l’authentification séparément
  26. 23. Distinguer 401 de 403
  27. 24. Vérifier l’autorisation sur le tenant/la ressource
  28. 25. Diagnostiquer un 404
  29. 26. Diagnostiquer un 405
  30. 27. Diagnostiquer un 409
  31. 28. Diagnostiquer un 412
  32. 29. Diagnostiquer un 415
  33. 30. Diagnostiquer un 422
  34. 31. Diagnostiquer un 429
  35. 32. Éviter les tempêtes de nouvelles tentatives
  36. 33. Réessayer uniquement lorsque la sémantique de l’opération le permet
  37. 34. Utiliser des clés d’idempotence pour les créations réessayables lorsqu’elles sont prises en charge
  38. 35. Diagnostiquer un 500
  39. 36. Diagnostiquer un 502
  40. 37. Diagnostiquer un 503
  41. 38. Diagnostiquer un 504
  42. 39. Identifier quelle couche a renvoyé l’erreur
  43. 40. Mesurer le temps jusqu’au premier octet
  44. 41. Mesurer la taille de la réponse
  45. 42. Vérifier la compression
  46. 43. Vérifier la pagination avant d’incriminer la latence
  47. 44. Reproduire une page précise
  48. 45. Garder des filtres identiques en comparant les pages
  49. 46. Valider la structure de la réponse JSON
  50. 47. Inspecter les en-têtes de la réponse indépendamment de l’analyse JSON
  51. 48. Vérifier l’encodage des caractères si le texte est corrompu
  52. 49. Vérifier la taille de la requête en cas de 413
  53. 50. Vérifier la taille des en-têtes en cas de 431
  54. 51. Tester CORS indépendamment de l’accessibilité de l’API
  55. 52. Si cURL fonctionne mais que le navigateur échoue
  56. 53. Si cela fonctionne en local mais échoue en CI
  57. 54. Si cela fonctionne en local mais échoue dans un conteneur
  58. 55. Si une seule région échoue
  59. 56. Si un seul client échoue
  60. 57. Si tous les clients échouent en même temps
  61. 58. Si les échecs commencent après un déploiement
  62. 59. Si les échecs sont intermittents
  63. 60. Repérer les schémas liés à l’expiration des jetons
  64. 61. Empêcher les ruées sur le renouvellement des jetons
  65. 62. Vérifier la synchronisation des horloges
  66. 63. Vérifier le comportement de réutilisation des connexions
  67. 64. Tester des requêtes répétées
  68. 65. Comparer les versions HTTP lorsque c’est pertinent
  69. 66. Inspecter la version HTTP négociée
  70. 67. Ne pas confondre délai d’expiration du client et du serveur
  71. 68. Aligner volontairement les budgets de délai d’expiration
  72. 69. Éviter de réessayer au-delà de l’échéance de l’appelant
  73. 70. Vérifier les dépendances en aval pour les requêtes lentes
  74. 71. Suivre séparément la durée de chaque dépendance
  75. 72. Vérifier le comportement des requêtes en base de données
  76. 73. Vérifier l’épuisement du pool de connexions
  77. 74. Vérifier la saturation des threads/de la boucle d’événements
  78. 75. Vérifier le coût de sérialisation des réponses très volumineuses
  79. 76. Vérifier les transformations effectuées par la passerelle
  80. 77. Vérifier le WAF/la stratégie de sécurité
  81. 78. Vérifier la mise en cache
  82. 79. Contourner le cache uniquement si l’API prend en charge une voie de diagnostic sûre
  83. 80. Comparer le comportement de l’ETag
  84. 81. Vérifier l’idempotence en cas d’échec d’écriture
  85. 82. Distinguer un échec de transport d’un échec HTTP
  86. 83. Vérifier le code de sortie de cURL
  87. 84. Ne pas masquer le corps de l’erreur dans l’automatisation
  88. 85. Consigner un enregistrement d’incident minimal
  89. 86. Comparer les requêtes qui fonctionnent et celles qui échouent
  90. 87. Reproduire avec la plus petite requête possible
  91. 88. Ne modifier qu’une variable à la fois
  92. 89. Ne pas désactiver les contrôles de sécurité pour faire passer le test
  93. 90. S’arrêter lorsque les éléments pointent en dehors de l’API
  94. Interpréter le résultat
  95. Points à vérifier
  96. Les échecs se concentrent sur un seul client
  97. Les échecs se concentrent sur une seule adresse IP de backend
  98. Les échecs commencent à l’expiration du jeton
  99. Le corps d’un 5xx est du HTML
  100. Les 429 augmentent après la première réponse de limitation
  101. TTFB élevé mais CPU de l’API sain
  102. API rapide en local, lente via la passerelle
  103. Dépassement de délai d’un POST suivi d’enregistrements en double
  104. Notes de production
  105. La qualité de la reproduction compte
  106. Protéger les secrets dans les diagnostics
  107. Délais d’expiration et nouvelles tentatives interagissent
  108. Les passerelles modifient la surface de diagnostic
  109. La supervision doit préserver la corrélation
  110. Une requête réussie ne prouve pas que tout est sain
  111. Erreurs fréquentes
  112. 1. Commencer par le code de l’application avant de vérifier le DNS/le TLS/le statut
  113. 2. Tester une requête différente de celle qui échoue
  114. 3. Considérer 401 et 403 comme interchangeables
  115. 4. Augmenter les délais d’expiration avant d’avoir trouvé la dépendance lente
  116. 5. Réessayer automatiquement chaque échec
  117. 6. Utiliser --insecure comme correctif TLS permanent
  118. 7. Partager des traces détaillées contenant des secrets
  119. 8. Supposer que chaque 5xx provient du code de l’application
  120. 9. Ne regarder que la latence moyenne
  121. 10. Modifier plusieurs choses à la fois
  122. Étape suivante
  123. 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.

Étape suivante

Utilisez la première couche en échec pour décider de ce qu’il faut examiner ensuite.

  • Aucune résolution DNS → examinez le résolveur, le VNet/VPC, le DNS du conteneur, le VPN et le proxy.
  • Échec de connexion → examinez l’endpoint, le port, le pare-feu, le listener et le routage.
  • Échec TLS → examinez le nom d’hôte, la chaîne de certificats, la confiance, le mTLS et l’horloge système.
  • 401 → examinez la validité du jeton/de la clé, l’émetteur, l’audience et l’expiration.
  • 403 → examinez le scope, le rôle, le tenant, le WAF et la stratégie IP/de sécurité.
  • 404/405 → examinez la route, la méthode, la version et le mappage de la passerelle.
  • 409/412 → examinez les règles d’état, de version et de concurrence.
  • 415/422 → examinez le Content-Type, le sérialiseur, le payload et la validation métier.
  • 429 → examinez les limites de débit, la concurrence, les nouvelles tentatives et l’identité de l’appelant.
  • 500 → corrélez l’identifiant de requête avec les journaux de l’application.
  • 502/503/504 → examinez la passerelle ainsi que les dépendances en amont/du backend.
  • TTFB élevé → examinez l’exécution côté serveur et la durée des appels en aval.
  • TTFB faible, total élevé → examinez la taille du payload, la compression et le transfert réseau.
  • cURL réussit mais l’application échoue → comparez précisément les en-têtes, le proxy, l’authentification, le TLS, les redirections et le comportement des délais d’expiration.
  • Rien d’évident n’apparaît → comparez les requêtes qui fonctionnent et celles qui échouent, et ne modifiez qu’une variable à la fois.

← Tous les aide-mémoire