Parcourir les aide-mémoire · API

Technologie: APICatégorie: Conception HTTP et APINiveau: IntermédiaireMis à jour

Codes de statut HTTP pour les développeurs

Interprétez et utilisez correctement les codes de statut HTTP lorsque vous concevez et diagnostiquez des API, avec des conseils pratiques sur les succès, les redirections, les erreurs client, les erreurs serveur, les nouvelles tentatives et les choix de conception d’API.

Sur cette page
  1. Problème
  2. Réponse rapide
  3. Code / commandes
  4. 1. Inspecter le code de statut avec cURL
  5. 2. Inspecter les en-têtes et le corps ensemble
  6. 3. Faire échouer les scripts en cas d’erreur HTTP
  7. 4. 200 OK
  8. 5. 201 Created
  9. 6. 202 Accepted
  10. 7. 204 No Content
  11. 8. 206 Partial Content
  12. 9. 301 Moved Permanently
  13. 10. 302 Found
  14. 11. 303 See Other
  15. 12. 304 Not Modified
  16. 13. 307 Temporary Redirect
  17. 14. 308 Permanent Redirect
  18. 15. 400 Bad Request
  19. 16. 401 Unauthorized
  20. 17. 403 Forbidden
  21. 18. 404 Not Found
  22. 19. 405 Method Not Allowed
  23. 20. 406 Not Acceptable
  24. 21. 408 Request Timeout
  25. 22. 409 Conflict
  26. 23. 410 Gone
  27. 24. 412 Precondition Failed
  28. 25. 413 Content Too Large
  29. 26. 414 URI Too Long
  30. 27. 415 Unsupported Media Type
  31. 28. 422 Unprocessable Content
  32. 29. 428 Precondition Required
  33. 30. 429 Too Many Requests
  34. 31. 431 Request Header Fields Too Large
  35. 32. 500 Internal Server Error
  36. 33. 501 Not Implemented
  37. 34. 502 Bad Gateway
  38. 35. 503 Service Unavailable
  39. 36. 504 Gateway Timeout
  40. 37. Distinguer 408 de 504
  41. 38. Distinguer 400 de 422
  42. 39. Distinguer 409 de 422
  43. 40. Distinguer 401 de 403
  44. 41. Distinguer 404 des collections vides
  45. 42. Ne pas renvoyer 404 par défaut pour une recherche vide
  46. 43. Utiliser 201 pour la création, pas pour chaque POST
  47. 44. Utiliser 204 uniquement lorsqu’aucun corps n’est nécessaire
  48. 45. Utiliser 202 pour un véritable traitement asynchrone
  49. 46. Utiliser Location pour les ressources créées ou asynchrones lorsque c’est utile
  50. 47. Utiliser les ETags pour la concurrence optimiste
  51. 48. Renvoyer des erreurs lisibles par une machine
  52. 49. Ne pas exposer les traces de pile
  53. 50. Inclure un identifiant de requête/de corrélation
  54. 51. Préserver avec discernement les statuts utiles venant de l’amont
  55. 52. Ne pas relayer aveuglément chaque statut venant de l’amont
  56. 53. Ne réessayer que les statuts adaptés à l’opération
  57. 54. Ne pas réessayer aveuglément la plupart des erreurs 4xx
  58. 55. 409 peut être réessayable ou non
  59. 56. Respecter Retry-After
  60. 57. Temporiser plutôt que réessayer en boucle serrée
  61. 58. Utiliser des clés d’idempotence pour les créations réessayables lorsqu’elles sont prises en charge
  62. 59. Vérifier d’où provient le statut
  63. 60. Vérifier le Content-Type des erreurs
  64. 61. Journaliser le statut par endpoint et par identité de l’appelant, en toute sécurité
  65. 62. Superviser les classes de statut, pas seulement 500
  66. 63. Séparer les 4xx attendus des défauts du serveur
  67. 64. Investiguer les pics soudains de 401
  68. 65. Investiguer les pics soudains de 403
  69. 66. Investiguer les pics soudains de 404
  70. 67. Investiguer les 429 par identité et par endpoint
  71. 68. Investiguer les 500 à l’aide des identifiants de requête
  72. 69. Investiguer les 502 du côté de la connectivité en amont
  73. 70. Investiguer les 503 du côté de la disponibilité et de la surcharge
  74. 71. Investiguer les 504 du côté de la latence des dépendances
  75. 72. Ne pas transformer chaque exception en 400
  76. 73. Ne pas transformer chaque échec en 500
  77. 74. Garder une sémantique de statut stable d’une version à l’autre
  78. 75. Utiliser le statut avec un code d’erreur métier
  79. 76. Éviter d’inventer des dizaines de codes numériques pseudo-HTTP
  80. 77. Documenter le comportement des nouvelles tentatives
  81. 78. Suivre une séquence de diagnostic
  82. Interpréter le résultat
  83. Points à vérifier
  84. 401 pour tous les clients
  85. 403 pour une seule opération
  86. 404 après un déploiement
  87. 409 lors de mises à jour concurrentes
  88. 422 avec un JSON par ailleurs valide
  89. 429 suivi d’encore plus de trafic
  90. 502 / 504 uniquement via la passerelle
  91. 500 avec du HTML au lieu de JSON
  92. Notes de production
  93. Les codes de statut font partie du contrat d’API
  94. Ne pas se fier au seul code de statut pour l’observabilité
  95. Les nouvelles tentatives relèvent d’une décision de systèmes distribués
  96. Les passerelles peuvent réécrire les réponses
  97. La sécurité peut influencer volontairement le choix du statut
  98. Erreurs fréquentes
  99. 1. Interpréter 401 comme « authentifié mais non autorisé »
  100. 2. Renvoyer 500 pour des erreurs de validation
  101. 3. Renvoyer 200 avec { "success": false } pour chaque échec
  102. 4. Réessayer chaque 5xx
  103. 5. Réessayer chaque 409
  104. 6. Considérer 202 comme un succès terminé
  105. 7. Envoyer un corps avec 204
  106. 8. Utiliser 206 pour la pagination normale d’une API
  107. 9. Supposer que chaque 502/504 provient du code applicatif
  108. 10. Exposer les détails internes des exceptions dans les réponses 500
  109. Étape suivante
  110. Pour aller plus loin

Problème

Une API a renvoyé 400, 401, 404, 409, 429 ou 500, et vous devez savoir ce que cela vous apprend réellement.

Les codes de statut ne sont utiles que s’ils sont interprétés dans leur contexte.

Une bonne démarche de diagnostic distingue :

  • les problèmes de syntaxe de la requête
  • les échecs d’authentification
  • les échecs d’autorisation
  • les ressources manquantes
  • les conflits d’état
  • les erreurs de validation
  • les limites de débit
  • les défaillances de passerelle
  • les défaillances applicatives
  • les problèmes temporaires de disponibilité du service

L’objectif est d’utiliser le code de statut comme un signal d’orientation pour la suite de l’investigation, et non comme le diagnostic complet.

Réponse rapide

Commencez par la classe du code de statut :

1xx
→ informatif

2xx
→ la requête a réussi

3xx
→ redirection / réponse liée au cache

4xx
→ la requête ne peut pas aboutir telle qu’elle a été envoyée

5xx
→ le serveur ou un service en amont n’a pas pu traiter une requête valide

Pour les échecs d’API courants :

400
→ requête mal formée ou invalide

401
→ authentification manquante ou invalide

403
→ authentifié mais non autorisé

404
→ ressource ou route introuvable

409
→ la requête entre en conflit avec l’état actuel de la ressource

412
→ échec de la précondition

415
→ type de média de la requête non pris en charge

422
→ requête syntaxiquement valide mais échec sémantique/de validation

429
→ limite de débit / trop de requêtes

500
→ défaillance inattendue du serveur

502
→ l’amont a renvoyé une réponse invalide/en échec

503
→ service temporairement indisponible

504
→ délai dépassé en amont

Inspectez toujours :

statut
+
en-têtes de la réponse
+
corps de la réponse
+
identifiant de requête/de corrélation

avant de décider où se situe le problème.

Code / commandes

1. Inspecter le code de statut avec cURL

curl \
  --silent \
  --output response.json \
  --write-out "%{http_code}\n" \
  "https://api.example.com/v1/reports"

Cette commande enregistre le corps séparément et affiche le statut HTTP.


2. Inspecter les en-têtes et le corps ensemble

curl \
  --include \
  "https://api.example.com/v1/reports"

Utile pour un diagnostic interactif.

Recherchez :

  • Content-Type
  • Retry-After
  • WWW-Authenticate
  • les en-têtes de cache
  • les en-têtes de passerelle/proxy
  • les identifiants de requête/de corrélation

3. Faire échouer les scripts en cas d’erreur HTTP

curl \
  --silent \
  --show-error \
  --fail-with-body \
  "https://api.example.com/v1/reports"

Sans --fail*, cURL peut renvoyer le code de sortie de processus 0 même lorsque la réponse HTTP est 404 ou 500.


4. 200 OK

Usages typiques :

GET réussi
mise à jour synchrone réussie
action réussie avec corps de réponse

Exemple :

HTTP/1.1 200 OK
Content-Type: application/json
{
  "reportId": "rpt-123",
  "status": "ready"
}

À utiliser lorsque la requête a réussi et qu’une représentation de réponse normale est renvoyée.


5. 201 Created

À utiliser lorsque la requête crée avec succès une nouvelle ressource.

Réponse typique :

HTTP/1.1 201 Created
Location: /v1/reports/rpt-123
Content-Type: application/json
{
  "reportId": "rpt-123"
}

Lorsque c’est possible, renvoyez un en-tête Location qui identifie la ressource créée.


6. 202 Accepted

À utiliser lorsque le serveur accepte la requête mais que le traitement aura lieu de manière asynchrone.

Exemple :

HTTP/1.1 202 Accepted
Location: /v1/jobs/job-456
{
  "jobId": "job-456",
  "status": "queued"
}

202 ne signifie pas que l’opération en arrière-plan s’est terminée avec succès.

Fournissez une ressource de statut ou un mécanisme de rappel (callback) ou d’événement lorsque l’appelant a besoin du résultat final.


7. 204 No Content

À utiliser lorsque la requête réussit et qu’il n’y a volontairement aucun corps de réponse.

Usages courants :

DELETE réussi
mise à jour réussie sans représentation renvoyée

Exemple :

HTTP/1.1 204 No Content

N’envoyez pas de corps JSON avec une réponse 204.


8. 206 Partial Content

Utilisé pour les requêtes de plage (range requests) réussies.

Scénario typique :

téléchargement de fichier volumineux
streaming multimédia
transfert pouvant être repris

La réponse inclut des en-têtes liés aux plages, comme Content-Range.

N’utilisez pas 206 simplement parce qu’une API renvoie une partie d’un jeu de données logique via la pagination.


9. 301 Moved Permanently

À utiliser pour une redirection permanente lorsque c’est approprié.

Les clients peuvent mettre en cache les redirections permanentes.

Pour les API, soyez prudent quant au comportement des méthodes et à la compatibilité des clients lorsque vous redirigez des requêtes autres que GET.


10. 302 Found

Une redirection temporaire historiquement très utilisée par les navigateurs et les serveurs.

Le comportement des méthodes côté client lors des redirections peut varier selon le contexte.

Pour les API où il est important de conserver la méthode d’origine, 307 ou 308 est généralement plus clair.


11. 303 See Other

Utile après une opération lorsque le client doit récupérer une autre ressource avec GET.

Exemple :

POST crée/démarre l’opération
→ 303
→ GET sur l’URL du résultat/du statut

12. 304 Not Modified

Utilisé avec les requêtes conditionnelles.

Exemple de requête :

If-None-Match: "abc123"

Réponse possible :

HTTP/1.1 304 Not Modified

Cela indique au client que sa représentation en cache peut toujours être utilisée.

304 n’est pas une réponse de succès normale avec un corps.


13. 307 Temporary Redirect

Redirection temporaire qui conserve la méthode HTTP et le corps de la requête.

Utile lorsqu’une requête d’API doit être répétée vers un autre URI sans transformer un POST/PUT/PATCH en sémantique GET.


14. 308 Permanent Redirect

Redirection permanente qui conserve la sémantique de la méthode et du corps.

À utiliser avec précaution, car les redirections permanentes peuvent être mises en cache.


15. 400 Bad Request

À utiliser lorsque la requête est mal formée ou ne peut pas être traitée en raison de la syntaxe ou des données fournies par le client.

Exemples :

JSON invalide
champ obligatoire manquant
syntaxe de paramètre de requête incorrecte
format de date invalide

Exemple de corps :

{
  "error": "invalid_request",
  "message": "startDate must use YYYY-MM-DD"
}

Ne renvoyez pas 500 pour un problème de validation que le client peut corriger.


16. 401 Unauthorized

Malgré son nom, 401 signifie normalement :

authentification requise, manquante ou invalide

Exemples :

  • jeton Bearer manquant
  • jeton expiré
  • signature invalide
  • émetteur/audience du jeton incorrects
  • identifiant d’API invalide

Pour les schémas d’authentification HTTP, incluez un challenge WWW-Authenticate approprié le cas échéant.


17. 403 Forbidden

À utiliser lorsque le serveur comprend la requête et que l’appelant est authentifié ou identifié d’une autre manière, mais que l’accès n’est pas autorisé.

Exemples :

  • scope requis manquant
  • rôle incorrect
  • une stratégie du tenant refuse l’accès
  • la vérification de propriété de la ressource échoue

Distinction habituelle :

401
→ qui êtes-vous / votre identifiant est invalide

403
→ nous savons qui vous êtes, mais vous ne pouvez pas faire cela

18. 404 Not Found

À utiliser lorsque la ressource ou la route demandée est introuvable.

Exemples :

identifiant de rapport inconnu
chemin incorrect
ressource supprimée
route de version d’API inconnue

Certaines API renvoient volontairement 404 au lieu de 403 pour ne pas révéler l’existence d’une ressource protégée.


19. 405 Method Not Allowed

À utiliser lorsque la route existe mais ne prend pas en charge la méthode HTTP demandée.

Exemple :

GET /reports/123
→ pris en charge

POST /reports/123
→ non pris en charge

Une réponse doit généralement inclure un en-tête Allow qui indique les méthodes prises en charge.


20. 406 Not Acceptable

À utiliser lorsque le serveur ne peut pas produire une représentation acceptable selon l’en-tête Accept du client.

Exemple :

Accept: application/xml

alors que l’API ne prend en charge que JSON.

C’est moins courant dans les API qui exposent un seul format de réponse fixe.


21. 408 Request Timeout

Indique que le serveur a dépassé son délai en attendant la requête du client.

Ne le confondez pas avec :

504 Gateway Timeout

qui signifie qu’une passerelle/un proxy a dépassé son délai en attendant un service en amont.


22. 409 Conflict

À utiliser lorsque la requête entre en conflit avec l’état actuel de la ressource.

Bons exemples :

clé métier unique en double
conflit de version/d’état
la ressource existe déjà selon une règle d’unicité
opération invalide dans l’état actuel du cycle de vie

Exemple :

{
  "error": "state_conflict",
  "message": "Report is already finalized."
}

409 convient souvent mieux qu’un 400 générique lorsque le problème concerne précisément l’état actuel de la ressource.


23. 410 Gone

À utiliser lorsqu’une ressource a existé mais a été volontairement supprimée, et que le serveur veut indiquer que cette absence est définitive.

Ne l’utilisez que si cette distinction avec 404 a une réelle utilité opérationnelle.


24. 412 Precondition Failed

Utilisé lorsqu’une précondition d’une requête conditionnelle échoue.

Exemple de requête avec concurrence optimiste :

If-Match: "version-42"

Si la ressource a désormais un ETag différent :

HTTP/1.1 412 Precondition Failed

C’est utile pour éviter les mises à jour perdues.


25. 413 Content Too Large

À utiliser lorsque le corps de la requête dépasse les limites acceptées par le serveur ou un intermédiaire.

Causes typiques :

  • fichier trop volumineux
  • payload JSON trop volumineux
  • limite de taille du corps de requête au niveau du proxy/de la passerelle

L’échec peut se produire avant que l’application ne reçoive la requête.


26. 414 URI Too Long

À utiliser lorsque l’URI de la requête dépasse ce que le serveur ou un intermédiaire accepte.

Cause courante :

placer un très grand filtre/une très grande liste dans les paramètres de requête

Déplacez les entrées structurées volumineuses dans un corps de requête approprié lorsque la sémantique de l’API le permet.


27. 415 Unsupported Media Type

À utiliser lorsque le Content-Type de la requête n’est pas pris en charge.

Exemple :

Content-Type: application/xml

envoyé à un endpoint qui n’accepte que :

application/json

Vérifiez l’en-tête réellement envoyé, pas seulement ce que le code client était censé envoyer.


28. 422 Unprocessable Content

À utiliser lorsque la syntaxe et le type de média de la requête sont valides, mais que le contenu ne peut pas être traité sur le plan sémantique.

Exemple :

{
  "startDate": "2026-11-01",
  "endDate": "2026-10-01"
}

Réponse possible :

HTTP/1.1 422 Unprocessable Content
{
  "error": "validation_failed",
  "fields": {
    "endDate": "Must be on or after startDate"
  }
}

Certaines API utilisent 400 pour tous les échecs de validation. La cohérence compte davantage que le fait de forcer chaque règle de validation vers 422.


29. 428 Precondition Required

À utiliser lorsque le serveur exige une requête conditionnelle pour éviter les mises à jour perdues.

Exemple d’exigence :

If-Match: "etag-value"

Cela permet d’imposer la concurrence optimiste.


30. 429 Too Many Requests

À utiliser lorsque l’appelant a dépassé un quota de débit ou de concurrence.

Réponse typique :

HTTP/1.1 429 Too Many Requests
Retry-After: 30

Réaction du client :

respecter Retry-After
réduire la concurrence
utiliser un backoff borné
éviter les tempêtes de nouvelles tentatives

Ne sollicitez pas le service encore plus vite après avoir reçu un 429.


31. 431 Request Header Fields Too Large

Utilisé lorsque les en-têtes de la requête sont trop volumineux.

Causes courantes :

  • cookies surdimensionnés
  • JWT très volumineux
  • en-têtes de proxy répétés
  • en-têtes personnalisés excessifs

La requête peut être rejetée par une passerelle avant d’atteindre l’application.


32. 500 Internal Server Error

À utiliser pour les défaillances inattendues côté serveur lorsqu’aucun statut plus précis ne s’applique.

Exemples :

exception non gérée
violation d’invariant inattendue
bug interne

N’exposez pas de traces de pile (stack traces), de secrets, de SQL ni de chemins internes dans la réponse destinée au client.

Renvoyez un identifiant de corrélation/de requête pour le support.


33. 501 Not Implemented

Signifie que le serveur ne prend pas en charge la fonctionnalité nécessaire pour satisfaire la requête.

Ce n’est normalement pas le bon statut pour :

feature flag désactivé
endpoint temporairement indisponible
état non pris en charge propre à une ressource

Ne l’utilisez que lorsque le serveur n’implémente réellement pas la capacité demandée.


34. 502 Bad Gateway

Une passerelle/un proxy a reçu une réponse invalide ou en échec d’un serveur en amont.

Architecture typique :

client
→ passerelle d’API
→ backend

Si la passerelle ne peut pas obtenir de réponse valide du backend :

502

Examinez le chemin entre la passerelle et le service en amont.


35. 503 Service Unavailable

À utiliser lorsque le service est temporairement incapable de traiter les requêtes.

Exemples :

  • maintenance
  • dépendance surchargée
  • pool de backends indisponible
  • délestage de charge volontaire (load shedding)

Un en-tête Retry-After peut être utile lorsque le serveur sait à quel moment il convient de réessayer.


36. 504 Gateway Timeout

Une passerelle/un proxy n’a pas reçu de réponse en temps voulu d’un service en amont.

Chemin typique :

client
→ passerelle
→ backend/dépendance lent

Ne supposez pas que la passerelle elle-même est la cause racine.

Examinez la latence en amont et la configuration des délais d’expiration.


37. Distinguer 408 de 504

408
→ le serveur a dépassé son délai en attendant la requête du client

504
→ la passerelle a dépassé son délai en attendant une réponse de l’amont

Cette distinction aide à identifier dans quel sens du chemin de la requête le blocage s’est produit.


38. Distinguer 400 de 422

Une convention d’API utile :

400
→ requête mal formée / analyse / validation structurelle

422
→ requête structurellement valide avec des valeurs métier/sémantiques invalides

Il s’agit d’une convention de conception, pas d’une obligation pour toutes les API.

Choisissez un modèle d’erreur cohérent et documentez-le.


39. Distinguer 409 de 422

Utilisez 409 lorsque l’échec concerne principalement l’état actuel de la ressource :

conflit de version
état en double
transition de cycle de vie invalide car la ressource a changé

Utilisez 422 lorsque le contenu de la requête lui-même échoue à la validation sémantique.

Les deux peuvent se recouper. La cohérence est essentielle.


40. Distinguer 401 de 403

N’utilisez pas :

403 pour toute erreur d’authentification

Un modèle plus clair est :

authentification manquante/invalide
→ 401

authentifié mais autorisation insuffisante
→ 403

41. Distinguer 404 des collections vides

Requête :

GET /reports?merchant=abc

sans aucun rapport correspondant peut raisonnablement renvoyer :

200 OK
[]

L’endpoint de collection existe ; son résultat est vide.

À l’inverse :

GET /reports/nonexistent-id

peut renvoyer :

404

42. Ne pas renvoyer 404 par défaut pour une recherche vide

Une collection vide est généralement un résultat valide, pas un endpoint ou une ressource manquante.

Cette distinction simplifie le comportement des clients.


43. Utiliser 201 pour la création, pas pour chaque POST

POST ne signifie pas automatiquement 201.

Exemples :

POST /reports
crée une ressource de rapport
→ 201

POST /reports/123/run
démarre une exécution asynchrone
→ 202

POST /search
renvoie des résultats de requête
→ 200

Choisissez le statut en fonction du résultat, pas uniquement de la méthode HTTP.


44. Utiliser 204 uniquement lorsqu’aucun corps n’est nécessaire

Si vous devez renvoyer :

{
  "status": "deleted"
}

alors 200 peut être plus approprié.

Une réponse 204 ne doit pas contenir de corps de message.


45. Utiliser 202 pour un véritable traitement asynchrone

Ne renvoyez pas 202 simplement pour masquer un traitement synchrone lent.

Un bon contrat asynchrone doit donner à l’appelant un moyen de savoir quand le traitement est terminé :

URL de job
endpoint de statut
webhook
événement

46. Utiliser Location pour les ressources créées ou asynchrones lorsque c’est utile

Création :

HTTP/1.1 201 Created
Location: /v1/reports/rpt-123

Asynchrone :

HTTP/1.1 202 Accepted
Location: /v1/jobs/job-456

Cela rend explicite la prochaine action du client.


47. Utiliser les ETags pour la concurrence optimiste

Lecture :

ETag: "42"

Mise à jour :

If-Match: "42"

Si la ressource a changé :

412 Precondition Failed

Cela évite les mises à jour perdues silencieusement.


48. Renvoyer des erreurs lisibles par une machine

Préférez :

{
  "error": "validation_failed",
  "message": "Request validation failed.",
  "fields": {
    "startDate": "Required"
  },
  "requestId": "req-123"
}

à :

Une erreur s’est produite

Gardez des contrats d’erreur suffisamment stables pour que les clients puissent agir en conséquence.


49. Ne pas exposer les traces de pile

Mauvaise réponse en production :

{
  "error": "NullReferenceException at InternalService.cs:842"
}

Renvoyez une erreur externe sûre accompagnée d’un identifiant de requête.

Conservez les diagnostics détaillés dans des journaux serveur protégés.


50. Inclure un identifiant de requête/de corrélation

Exemple :

{
  "error": "internal_error",
  "message": "The request could not be completed.",
  "requestId": "req-123"
}

Le même identifiant doit apparaître dans la télémétrie du serveur/de la passerelle lorsque c’est possible.


51. Préserver avec discernement les statuts utiles venant de l’amont

Si votre API appelle un autre service, ne traduisez pas aveuglément chaque erreur en amont en :

500

Exemples :

délai dépassé en amont via la passerelle
→ peut-être 504

amont indisponible
→ peut-être 503

le client a fourni un identifiant de ressource invalide
→ peut-être conserver un comportement 4xx pertinent

Mais ne divulguez pas inutilement les détails des dépendances internes.


52. Ne pas relayer aveuglément chaque statut venant de l’amont

Votre API est responsable de son contrat public.

Un service interne peut renvoyer un statut qui n’a aucun sens pour votre client externe.

Traduisez de manière délibérée tout en conservant, côté serveur, l’observabilité du résultat d’origine en amont.


53. Ne réessayer que les statuts adaptés à l’opération

Les conditions potentiellement réessayables incluent souvent :

429
502
503
504

selon l’API et l’opération.

Mais la sûreté d’une nouvelle tentative dépend aussi :

méthode HTTP
idempotence
effets de bord de la requête
Retry-After
recommandations du fournisseur

N’utilisez pas de liste universelle de nouvelles tentatives.


54. Ne pas réessayer aveuglément la plupart des erreurs 4xx

Exemples :

400
401
403
404
415
422

exigent généralement de modifier la requête, l’identifiant, l’autorisation ou la ressource.

Une nouvelle tentative avec les mêmes données reproduit généralement le même échec.


55. 409 peut être réessayable ou non

Exemples :

conflit de concurrence optimiste
→ recharger la ressource et réessayer avec la nouvelle version

clé en double
→ réessayer la même requête de création est inutile

conflit temporaire de transition d’état
→ éventuellement réessayer après le changement d’état

Interprétez le corps de l’erreur et le contrat métier.


56. Respecter Retry-After

Retry-After peut être renvoyé avec des statuts tels que :

429
503

Les clients doivent l’utiliser lorsqu’il est présent et valide, plutôt que de réessayer immédiatement.


57. Temporiser plutôt que réessayer en boucle serrée

Mauvais :

la requête échoue
→ nouvelle tentative immédiate
→ nouvelle tentative immédiate
→ nouvelle tentative immédiate

Cela peut aggraver la surcharge.

Utilisez un backoff borné avec jitter lorsque c’est approprié.


58. Utiliser des clés d’idempotence pour les créations réessayables lorsqu’elles sont prises en charge

Exemple :

Idempotency-Key: 5f1b...

Si l’API le prend en charge, le serveur peut reconnaître les tentatives de création répétées et éviter les effets de bord en double.

Le mécanisme doit être implémenté par le serveur ; un en-tête aléatoire seul ne fait rien.


59. Vérifier d’où provient le statut

Un 502, 503 ou 504 peut provenir :

  • d’un CDN
  • d’un WAF
  • d’un équilibreur de charge
  • d’une passerelle d’API
  • d’un proxy inverse
  • de l’application

Inspectez les en-têtes et le corps.

Ne supposez pas que l’application a généré chaque réponse.


60. Vérifier le Content-Type des erreurs

Attendu :

application/json

Reçu :

text/html

Cela suggère souvent qu’un intermédiaire a généré une page d’erreur.

Utilisez :

curl --include ...

pour l’inspecter.


61. Journaliser le statut par endpoint et par identité de l’appelant, en toute sécurité

Dimensions utiles :

route
méthode
classe de statut
code de statut
identité du client/de l’application
tenant
latence
identifiant de requête

Évitez de journaliser les identifiants ou les payloads de requête sensibles.


62. Superviser les classes de statut, pas seulement 500

Vues opérationnelles utiles :

taux de 2xx
taux de 4xx
taux de 5xx
taux de 429
latence par statut

Une hausse soudaine des 401, 403, 404 ou 429 peut révéler un problème en production même si les 500 restent faibles.


63. Séparer les 4xx attendus des défauts du serveur

Un endpoint qui effectue beaucoup de validations peut légitimement renvoyer de nombreuses réponses 400/422.

Sur le plan opérationnel, distinguez :

entrées rejetées attendues
de
ruptures d’intégration client inattendues

Établissez une référence par endpoint et par client.


64. Investiguer les pics soudains de 401

Causes possibles :

  • clé de signature/certificat expiré
  • mauvaise configuration de déploiement
  • changement d’audience du jeton
  • problème d’horloge
  • panne du fournisseur d’authentification
  • échec de rotation des identifiants client

Un pic de 401 touchant de nombreux clients est différent du jeton expiré d’un seul utilisateur.


65. Investiguer les pics soudains de 403

Causes possibles :

  • modification de la stratégie d’autorisation
  • déploiement de scopes/rôles
  • défaut de mappage des tenants
  • mise à jour de la stratégie de la passerelle

L’authentification peut tout de même fonctionner correctement.


66. Investiguer les pics soudains de 404

Causes possibles :

  • le client est passé à une mauvaise version de l’API
  • le déploiement des routes a changé
  • URL de base incorrecte
  • identifiants de tenant/de ressource mal formés
  • problème de routage dans la passerelle

Tous les 404 ne signifient pas que des données ont été supprimées.


67. Investiguer les 429 par identité et par endpoint

Vérifiez :

quelle clé d’API/quel client/quel utilisateur
quel endpoint
débit des requêtes
concurrence des requêtes
comportement des nouvelles tentatives

Un seul appelant agressif peut générer une charge disproportionnée.


68. Investiguer les 500 à l’aide des identifiants de requête

Le message destiné au client doit rester sûr.

Utilisez l’identifiant de requête pour retrouver :

exception
appel de dépendance
requête de base de données
étape du pipeline

dans la télémétrie protégée.


69. Investiguer les 502 du côté de la connectivité en amont

Vérifiez :

état de santé du backend
réinitialisation de connexion
réponse invalide de l’amont
TLS vers le backend
journaux du proxy/de la passerelle

70. Investiguer les 503 du côté de la disponibilité et de la surcharge

Vérifiez :

nombre de backends sains
déploiement/maintenance
saturation des ressources
délestage de charge
panne d’une dépendance

71. Investiguer les 504 du côté de la latence des dépendances

Vérifiez :

délai d’expiration de la passerelle
durée côté backend
durée côté base de données
durée de l’API en aval
mise en file d’attente

Augmenter le délai d’expiration peut masquer le symptôme sans corriger la dépendance lente.


72. Ne pas transformer chaque exception en 400

Une défaillance inattendue de la base de données n’est pas une erreur de saisie du client.

Renvoyez un statut côté serveur lorsque c’est le serveur qui a échoué.

Mal classer les erreurs dégrade la supervision et le comportement des clients.


73. Ne pas transformer chaque échec en 500

Les erreurs client connues doivent utiliser des réponses 4xx pertinentes.

Cela permet aux clients de corriger leur comportement sans tout traiter comme une panne.


74. Garder une sémantique de statut stable d’une version à l’autre

Si :

création en double

renvoie 409 dans un endpoint et 500 dans un autre, le comportement du client devient plus difficile à implémenter.

La cohérence améliore l’utilisabilité de l’API et son exploitation.


75. Utiliser le statut avec un code d’erreur métier

Exemple :

HTTP/1.1 409 Conflict
{
  "error": "report_already_finalized",
  "message": "The report cannot be modified after finalization."
}

Le statut HTTP donne le sens général.

Le code d’erreur métier donne un sens précis et lisible par une machine.


76. Éviter d’inventer des dizaines de codes numériques pseudo-HTTP

Utilisez les statuts HTTP standard pour la sémantique transport/API.

Ajoutez un champ d’erreur métier stable lorsque des détails supplémentaires sont nécessaires.


77. Documenter le comportement des nouvelles tentatives

Pour chaque contrat d’erreur important, documentez :

statut
erreur métier
réessayable ?
nouveau jeton requis ?
nouvelle version de la ressource requise ?
nouvelle tentative automatique sûre ?

C’est plus utile que de publier une simple liste de codes de statut.


78. Suivre une séquence de diagnostic

1. Capturer le statut HTTP
2. Capturer séparément l’erreur de sortie de cURL/du client
3. Lire le corps de la réponse
4. Inspecter les en-têtes de la réponse
5. Capturer l’identifiant de requête
6. Identifier la couche qui a répondu
7. Déterminer la responsabilité client ou serveur
8. Décider si une nouvelle tentative est sûre
9. Corréler la télémétrie côté serveur

Interpréter le résultat

Code Interprétation pratique
200 Requête terminée avec succès
201 Ressource créée
202 Acceptée pour un traitement asynchrone
204 Succès sans corps de réponse
304 Représentation en cache toujours valide
400 Requête incorrecte, mal formée ou invalide
401 Authentification manquante ou invalide
403 Appelant non autorisé
404 Route/ressource introuvable
405 Méthode HTTP non autorisée pour la route
409 Conflit avec l’état actuel de la ressource
412 Échec de la précondition d’une requête conditionnelle
413 Corps de requête trop volumineux
415 Type de média de la requête non pris en charge
422 Échec sémantique/de validation
429 Limite de débit dépassée
500 Défaillance inattendue du serveur
502 La passerelle a reçu une réponse incorrecte de l’amont
503 Service temporairement indisponible
504 Délai dépassé par la passerelle en attendant l’amont

Le code de statut est un signal de classification.

Le corps de la réponse, les en-têtes, le contexte de la requête et la télémétrie du serveur fournissent le diagnostic.

Points à vérifier

401 pour tous les clients

Soupçonnez l’infrastructure ou la configuration d’authentification partagée avant de supposer que chaque identifiant a expiré indépendamment.

403 pour une seule opération

Vérifiez le rôle, le scope ou l’autorisation sur la ressource requis.

404 après un déploiement

Vérifiez le routage, la version et le chemin de base avant de supposer que les données ont disparu.

409 lors de mises à jour concurrentes

Recherchez des conflits de concurrence optimiste ou de transition d’état.

422 avec un JSON par ailleurs valide

Examinez les règles de validation des champs et les règles métier.

429 suivi d’encore plus de trafic

La stratégie de nouvelles tentatives du client crée peut-être une tempête de nouvelles tentatives (retry storm).

502 / 504 uniquement via la passerelle

Comparez l’état de santé direct du backend et la connectivité/latence entre la passerelle et le backend lorsque l’architecture le permet.

500 avec du HTML au lieu de JSON

Un intermédiaire a peut-être généré la réponse.

Inspectez les en-têtes pour identifier la couche qui a répondu.

Notes de production

Les codes de statut font partie du contrat d’API

Les modifier peut casser :

  • le comportement des nouvelles tentatives
  • la supervision
  • la logique des SDK
  • le comportement de l’interface utilisateur
  • les alertes

Traitez la sémantique des statuts comme un comportement versionné.

Ne pas se fier au seul code de statut pour l’observabilité

Enregistrez :

code d’erreur métier
identifiant de requête
endpoint
identité de l’appelant
latence
dépendance en amont

lorsque c’est pertinent.

Les nouvelles tentatives relèvent d’une décision de systèmes distribués

Un statut peut sembler transitoire, mais réessayer une opération non idempotente peut dupliquer les effets de bord.

Combinez la sémantique des statuts avec les garanties d’idempotence.

Les passerelles peuvent réécrire les réponses

L’application peut renvoyer un résultat alors que :

  • la passerelle
  • le proxy
  • le CDN
  • le WAF

modifie le statut ou le corps visible de l’extérieur.

Diagnostiquez l’ensemble du chemin de la requête.

La sécurité peut influencer volontairement le choix du statut

Certaines API renvoient 404 au lieu de 403 pour ne pas révéler l’existence d’une ressource protégée.

Documentez et testez la stratégie choisie.

Erreurs fréquentes

1. Interpréter 401 comme « authentifié mais non autorisé »

Dans l’usage normal des API HTTP, cette situation correspond généralement à 403.

2. Renvoyer 500 pour des erreurs de validation

Les clients ne peuvent pas distinguer une entrée incorrecte d’une défaillance du service.

3. Renvoyer 200 avec { "success": false } pour chaque échec

Cela masque la sémantique de l’échec aux clients HTTP, aux passerelles et à la supervision.

4. Réessayer chaque 5xx

Une nouvelle tentative peut être dangereuse ou aggraver la surcharge.

5. Réessayer chaque 409

La signification d’un conflit dépend du domaine métier.

6. Considérer 202 comme un succès terminé

Il signifie seulement que la requête a été acceptée.

7. Envoyer un corps avec 204

204 signifie aucun contenu de réponse.

8. Utiliser 206 pour la pagination normale d’une API

206 relève de la sémantique HTTP de contenu partiel/de plage, pas des jeux de données ordinaires paginés.

9. Supposer que chaque 502/504 provient du code applicatif

Ils sont souvent générés par les passerelles.

10. Exposer les détails internes des exceptions dans les réponses 500

Utilisez des erreurs sûres accompagnées d’un identifiant de requête.

Étape suivante

Utilisez le statut pour orienter l’investigation.

  • 400 / 415 / 422 → examinez la syntaxe de la requête, le type de contenu et la validation.
  • 401 → examinez le jeton/la clé/le certificat d’authentification ainsi que l’émetteur, l’audience et l’expiration.
  • 403 → examinez le scope, le rôle, le tenant et l’autorisation sur la ressource.
  • 404 → vérifiez la route, la version de l’API, l’identifiant de la ressource et le routage de la passerelle.
  • 409 / 412 → examinez la logique d’état, de version et de concurrence.
  • 429 → examinez le débit de l’appelant, la concurrence, Retry-After et la stratégie de nouvelles tentatives.
  • 500 → corrélez l’identifiant de requête avec les journaux de l’application.
  • 502 → examinez la connectivité et les réponses entre la passerelle et l’amont.
  • 503 → examinez la disponibilité du service, la surcharge, la maintenance et les dépendances.
  • 504 → examinez la latence en amont et les limites de délai d’expiration.
  • Le statut est ambigu ou incohérent → reproduisez le problème avec cURL et inspectez l’ensemble des en-têtes et du corps.
  • Besoin d’un diagnostic de bout en bout → passez à Diagnostiquer les requêtes d’API.

← Tous les aide-mémoire