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