503 Service Unavailable

Ce que signifie cette erreur et comment la reconnaître

• Le navigateur, le client API ou l’outil de monitoring signale 503 Service Unavailable ou Service Temporarily Unavailable.
• L’erreur apparaît lors d’un trafic important et disparaît lorsque la demande diminue.
• Le site reste indisponible après une mise à jour du CMS ou un déploiement parce que le mode maintenance n’a pas été désactivé.
• L’erreur persiste lorsqu’une base de données, un service de cache ou une API upstream requis est indisponible.
• Seules certaines URL, certains clients, certains modèles de requêtes ou certains backends reçoivent des réponses 503 en raison d’une limitation de débit, d’une règle WAF, du routage ou d’un health check de load balancer défaillant.
• Les en-têtes de réponse ou une page d’erreur générée par un proxy indiquent que la requête n’a peut-être pas atteint l’application.

Causes principales, classées par probabilité

1. Surcharge du serveur — Le processeur, la mémoire, les connexions actives, les workers du serveur web, les workers PHP-FPM ou les connexions à la base de données sont épuisés par la demande habituelle ou par un pic de trafic.
2. Mode maintenance bloqué — Une mise à jour du CMS ou un déploiement active un indicateur de maintenance, mais ne le supprime pas après une interruption. Dans WordPress, il peut s’agir d’un fichier .maintenance orphelin.
3. Dépendance requise indisponible — L’application ne peut pas joindre une base de données, une couche de cache ou une API interne nécessaire au traitement de la requête. La dépendance peut fonctionner, tout en restant inaccessible depuis l’hôte ou le réseau de l’application.
4. Limitation de débit ou comportement du WAF intentionnel — Un limiteur de débit ou un pare-feu applicatif (WAF) peut renvoyer des réponses 503 lorsque le trafic dépasse un seuil ou correspond à une règle de sécurité.
5. Health check défaillant du load balancer — Un check peut considérer comme indisponibles des instances backend saines parce qu’il utilise le mauvais chemin ou attend le mauvais code de réponse.
6. Problème de configuration du proxy ou de l’upstream — Un reverse proxy, un CDN ou un service upstream peut générer l’erreur 503 avant que l’application ne reçoive la requête.

Comment corriger le problème

1. Identifiez la couche qui a généré l’erreur 503

Vérifiez les en-têtes de réponse et comparez les journaux de l’application, du serveur web, du reverse proxy, du CDN ou du WAF, ainsi que du load balancer. Déterminez si la réponse vient de l’application ou si elle a été générée avant que la requête ne l’atteigne. Vous éviterez ainsi de modifier les paramètres de l’application lorsque la couche bloquante se situe ailleurs.

2. Vérifiez l’utilisation des ressources au moment de l’erreur

Examinez le processeur, la mémoire, les connexions actives, les workers du serveur web, les workers PHP-FPM le cas échéant, ainsi que les connexions à la base de données. Utilisez des outils de monitoring en lecture seule tels que top ou htop, les tableaux de bord de l’hébergeur et le monitoring de l’infrastructure afin de déterminer si une limite a été atteinte.

• Si une ressource était proche de sa capacité maximale, considérez l’incident comme un problème de surcharge ou de capacité.
• Si l’utilisation des ressources était normale, recherchez un état de maintenance, des dépendances, des limites de débit, des règles WAF et des health checks.

3. Désactivez un état de maintenance incomplet

Pour WordPress, vérifiez que la mise à jour est terminée ou que le site est bien censé être en maintenance, puis connectez-vous via SFTP et recherchez dans la racine du site un fichier nommé .maintenance. Si la mise à jour est terminée mais que ce fichier est toujours présent, supprimez-le et testez à nouveau le site. La suppression du fichier modifie l’état de maintenance du site : ne le faites donc pas pendant une mise à jour ou un déploiement actif.

D’autres plateformes et outils de déploiement peuvent utiliser un fichier indicateur ou une variable d’environnement. Examinez le processus de mise à jour ou de déploiement pour déterminer ce qui active le mode maintenance et si son étape de nettoyage s’est exécutée après une interruption.

4. Testez les dépendances depuis le serveur d’application

Vérifiez que la base de données, la couche de cache telle que Redis ou Memcached, ainsi que les services internes requis sont actifs et accessibles depuis le serveur d’application. Recherchez les erreurs de connexion, les échecs d’authentification, les timeouts et les entrées correspondantes dans les journaux des services.

Une dépendance peut fonctionner globalement tout en étant inaccessible depuis un hôte d’application précis en raison des accès réseau, des identifiants, du routage ou d’une défaillance au niveau du service.

5. Traitez une véritable surcharge

Identifiez la ressource limitante avant d’augmenter un paramètre. Le goulot d’étranglement peut concerner le processeur, la mémoire, les connexions à la base de données, les connexions au serveur web ou les workers PHP-FPM.

Pour un soulagement à court terme, réduisez les traitements coûteux, augmentez une limite uniquement si l’hôte dispose d’une capacité disponible suffisante et si la modification est autorisée, ou ajoutez un cache pour les pages adaptées. En cas de demande récurrente, envisagez un CDN ou une couche de cache ainsi qu’une capacité backend supplémentaire, plutôt que d’augmenter les limites à répétition.

6. Vérifiez les limites de débit, les règles WAF et les health checks du load balancer

Examinez les journaux de Nginx, Apache, du CDN ou d’un autre proxy et des systèmes de sécurité afin d’identifier les règles qui renvoient intentionnellement des réponses 503. Inspectez les chemins des health checks, les codes de statut attendus et l’enregistrement des backends. Si seuls certains URL, clients ou backends échouent, ces éléments peuvent aider à distinguer un contrôle du trafic ou un problème de routage d’une panne complète du site.

7. Vérifiez la correction

Répétez la requête qui a échoué et consultez les journaux de l’application, du proxy et des dépendances. Confirmez que les requêtes normales aboutissent et, si possible, effectuez un test avec un niveau de trafic ou une heure de la journée similaires. Assurez-vous que la correction traite la condition déclenchante, plutôt que de supprimer uniquement un symptôme temporaire.

Prévention et vérification du correctif

• Assurez-vous que les scripts de déploiement et de mise à jour suppriment les indicateurs de maintenance dans une étape de nettoyage ou finally, y compris après des échecs partiels.
• Surveillez le processeur, la mémoire, les connexions actives, l’utilisation des workers et les connexions à la base de données, avec des alertes avant l’épuisement de la capacité.
• Mettez en cache les pages et les traitements de base de données adaptés afin que les pics de trafic consomment moins de capacité backend.
• Testez les health checks du load balancer avec le chemin correct et le code de réponse attendu.
• Examinez les modifications des limites de débit et du WAF afin de distinguer les réponses 503 intentionnelles des défaillances de service.
• Conservez les journaux de l’application, du proxy, des dépendances et de l’infrastructure pour la même période afin de pouvoir corréler les erreurs.
• Après une correction, vérifiez le site dans des conditions similaires à celles qui ont déclenché l’erreur initiale.

Questions fréquentes