Erreurs serveur HTTP 5xx : signification, diagnostic et solutions

Ce que signifie cette erreur et comment la reconnaître

Vous pouvez observer un ou plusieurs des symptômes suivants :

• Un site web ou une API renvoie un code d’état HTTP compris entre 500 et 599.
• La réponse est une erreur serveur générique, une erreur d’application ou une page personnalisée par un reverse proxy, un répartiteur de charge ou un CDN.
• Une seule route, opération ou endpoint d’API échoue tandis que les autres pages continuent de fonctionner.
• L’ensemble du service devient indisponible ou renvoie des erreurs de manière intermittente.
• Les requêtes ralentissent avant de se terminer par une réponse 504 ou une autre erreur 5xx liée à une passerelle.
• La réponse inclut un identifiant de requête, un identifiant du service en amont ou un en-tête d’erreur spécifique au serveur pouvant aider à identifier la couche à l’origine de la réponse.

Causes principales, classées par probabilité

Les causes probables, des plus courantes aux moins courantes, incluent :

1. Exceptions de l’application ou échec du traitement de la requête. Des erreurs d’application non gérées, des chemins de saisie invalides ou une modification de code défectueuse peuvent produire une réponse 500.
2. Déploiement ou modifications de configuration récents. Une version déployée, une modification de variable d’environnement, un changement de routage ou une erreur de configuration du serveur peut affecter une seule route ou l’ensemble du service.
3. Processus backend défaillants. Un processus d’application arrêté, instable, surchargé ou inaccessible peut amener un proxy à renvoyer une réponse 502 ou 503.
4. Défaillances des dépendances. Des erreurs de base de données, des services internes indisponibles, des services externes lents ou des pools de connexions épuisés peuvent se manifester par plusieurs codes 5xx différents.
5. Délais d’attente entre les couches. Une passerelle peut renvoyer une réponse 504 lorsqu’un service en amont ne répond pas dans le délai configuré ; des dépendances lentes peuvent en être la cause sous-jacente.
6. Pression sur les ressources. Une utilisation élevée du processeur ou de la mémoire, la saturation des workers, un disque plein ou des limites de connexions peuvent rendre un service indisponible ou provoquer l’expiration des requêtes.
7. Maintenance ou protection intentionnelle. Un service peut renvoyer une réponse 503 pendant une maintenance, une évacuation du trafic, une limitation du débit ou une protection contre la surcharge.
8. Comportement spécifique à la couche. Le même incident sous-jacent peut produire des codes différents selon que la réponse a été générée par l’application, le serveur web, le reverse proxy, le répartiteur de charge ou le CDN.

Comment corriger le problème

1. Documenter précisément l’échec

Notez le code d’état exact, l’URL ou l’opération d’API concernée, l’heure avec le fuseau horaire, la fréquence, le corps de la réponse et les en-têtes de réponse pertinents. Conservez tout identifiant de requête ou de trace. Si vous consultez simplement le site, transmettez ces informations au responsable du service au lieu de modifier les paramètres du serveur.

2. Identifier la couche qui génère la réponse

Comparez la page d’erreur ou le corps JSON, les en-têtes, les cookies et les identifiants du serveur avec une réponse connue comme fonctionnelle. Un corps d’erreur propre à un framework peut indiquer l’application ; une page personnalisée par une passerelle ou un CDN peut signifier que la requête a échoué avant que le serveur d’origine ne produise une réponse. Consultez les journaux du reverse proxy, du répartiteur de charge ou du CDN lorsque les journaux du serveur d’origine ne contiennent aucune requête correspondante.

3. Distinguer une panne générale d’un échec limité à une route

Testez un endpoint de vérification d’état autorisé et peu impactant, ainsi qu’une route connue comme non affectée. Si une seule route échoue, examinez son code applicatif, son accès aux données et ses dépendances spécifiques à la requête. Si toutes les routes échouent, donnez la priorité à l’état des processus, au déploiement, au routage, à la capacité et aux dépendances partagées. N’actualisez pas continuellement un endpoint de production pour remplacer une vérification d’état.

4. Corréler les journaux aux mêmes horodatages

Examinez ensemble les journaux de l’application, du serveur web, du proxy/répartiteur de charge et des dépendances. Recherchez d’abord l’identifiant de requête, puis affinez par horodatage et endpoint. Recherchez les traces de pile, les redémarrages de processus, les messages de refus de connexion, les codes d’état des services en amont, les messages d’expiration de délai, les appels de base de données échoués et les connexions rejetées. Supprimez les identifiants, jetons et données de requête sensibles avant de partager les journaux.

5. Vérifier les changements récents et l’état du service

Examinez les déploiements, les feature flags, les modifications de configuration, les mises à jour de certificats ou de routage, les opérations de maintenance et les changements de dépendances effectués peu avant le début des échecs. Vérifiez que les processus backend fonctionnent et passent leurs vérifications d’état. Si une modification récente est fortement corrélée à l’incident, utilisez la procédure de rollback approuvée du service et obtenez l’autorisation nécessaire ; ne redémarrez pas et ne rétablissez pas une version des systèmes de production sans approbation opérationnelle.

6. Vérifier les dépendances et la pression sur les ressources

Contrôlez l’accessibilité et la latence de la base de données, l’état des services internes, les réponses des dépendances externes, l’utilisation du pool de connexions, la profondeur des files d’attente, le processeur, la mémoire, l’espace disque, la disponibilité des workers et les limites de connexions. Une dépendance simplement lente peut provoquer une réponse 504 même si le processus de l’application fonctionne. Corrigez le composant limité ou défaillant au lieu de masquer le symptôme en augmentant les délais d’attente sans analyse.

7. Utiliser le code d’état pour orienter l’enquête

• 500 Internal Server Error: Commencez par les journaux de l’application, les erreurs du serveur, la route défaillante et les modifications récentes du code ou de la configuration.
• 502 Bad Gateway: Examinez la connexion entre le proxy et le service en amont, ainsi que la réponse de ce dernier. Vérifiez si le backend est arrêté, ferme les connexions, renvoie des données malformées ou est atteint via une route incorrecte.
• 503 Service Unavailable: Vérifiez l’état de maintenance, les vérifications de disponibilité ou d’état, les mécanismes de protection contre la surcharge, la disponibilité des processus et les dépendances partagées.
• 504 Gateway Timeout: Mesurez où le temps est passé. Vérifiez la latence du service en amont, les appels à la base de données ou aux services externes, les pools de connexions et les paramètres de délai d’attente à chaque couche.
• Autres codes 5xx: Utilisez la définition exacte du code et identifiez le composant qui l’a émis ; ne supposez pas que toutes les réponses 5xx ont la même cause.

8. Appliquer la correction autorisée la plus ciblée et vérifier sans risque

Corrigez le problème identifié — application, configuration, dépendance ou capacité — en suivant le processus de gestion des changements de l’environnement. Ensuite, vérifiez un endpoint de santé simple, l’opération précédemment défaillante et les fonctions dépendantes représentatives. Confirmez que les taux de réponses 5xx et la latence sont revenus à la normale sans créer d’écritures en double ni de charge supplémentaire. Si la correction implique une action modifiant l’état, comme le redémarrage d’un processus, l’évacuation du trafic ou la modification d’un délai d’attente, documentez l’impact attendu et obtenez d’abord l’autorisation nécessaire.

Prévention et vérification du correctif

• Surveillez le taux de réponses 5xx, la latence et la disponibilité par route, service et couche générant la réponse.
• Utilisez des vérifications de disponibilité et d’état qui reflètent les exigences réelles des dépendances sans créer une charge excessive.
• Conservez des identifiants de requête ou de trace cohérents entre les proxies, les applications et les dépendances.
• Définissez des délais d’attente et des limites de connexions bornés et réévalués à chaque frontière de service ; évitez que des appels externes lents consomment tous les workers.
• Déclenchez des alertes sur la saturation des ressources, les plantages de processus, la latence des bases de données, l’épuisement des pools de connexions et la pression sur le disque avant qu’ils ne provoquent des pannes généralisées.
• Utilisez des déploiements progressifs, un déplacement du trafic fondé sur l’état de santé et une procédure de rollback testée.
• Documentez les codes 5xx que chaque proxy, application et dépendance peut émettre afin que les intervenants ne traitent pas 500, 502, 503 et 504 comme interchangeables.
• Testez régulièrement le comportement en cas de dépendance dégradée et de surcharge dans un environnement autorisé.

Questions fréquentes