503 Service Unavailable : surcharge, maintenance et Retry-After

Vivant, et refusant le travail

Pour renvoyer un 503, il faut déjà que quelque chose tourne : il a accepté la connexion TCP, analysé la requête et généré une réponse. Ce seul fait exclut toute une classe de problèmes. L'hôte est en ligne, le chemin réseau fonctionne, le TLS s'est terminé, et le serveur web ou le proxy fonctionne. Ce qui manque, c'est la capacité ou la volonté.

La RFC 9110 ajoute une réserve : un serveur n'est pas obligé d'utiliser 503 en cas de surcharge. Certains refusent simplement la connexion à la place. Un 503 est donc la forme polie de la surcharge. Si vous obtenez une connexion refusée ou un délai dépassé plutôt qu'un 503, vous êtes face à un échec différent et généralement pire.

Deux voisins sont faciles à confondre. Un 504 Gateway Timeout signifie que le backend a été accepté puis n'a jamais répondu à temps ; la requête a été tentée. Un 503 signifie que la requête a été refusée avant même que du vrai travail ne commence. Toute la famille est comparée dans la vue d'ensemble des 5xx.

Retry-After, et pourquoi vous devriez toujours l'envoyer

La RFC 9110 permet à un 503 de porter un en-tête Retry-After, sous l'une de deux formes : un nombre de secondes à attendre, ou une date HTTP absolue.

HTTP/1.1 503 Service Unavailable
Retry-After: 300
Content-Type: text/html

Cela ne coûte rien. Les clients et bibliothèques bien élevés reculent pendant l'intervalle indiqué plutôt que de marteler un serveur déjà en difficulté. Les robots d'exploration des moteurs de recherche traitent l'URL comme temporairement indisponible et reviennent plus tard plutôt que de traiter la panne comme un retrait de contenu. Votre propre surveillance et vos outils de statut obtiennent un temps de rétablissement attendu explicite à afficher.

Un 503 n'est pas mis en cache par défaut, donc les intermédiaires ne continueront pas à le servir après que le service se rétablit.

Ce qui cause un 503

• Surcharge. Tous les threads de travail, processus ou emplacements de connexion sont occupés, donc les nouvelles requêtes sont rejetées plutôt que mises en file d'attente indéfiniment. Commence typiquement de façon intermittente aux heures de pointe et devient constant à mesure que la charge augmente.
• Mode maintenance. Un basculement intentionnel, depuis un drapeau de framework, un fichier de maintenance ou une règle de proxy. C'est un 503 qui fait exactement ce qu'il devrait.
• Une dépendance est hors service. Une application bien écrite qui ne peut pas atteindre sa base de données, son cache ou sa file d'attente devrait renvoyer 503 plutôt qu'une trace de pile, car la situation est temporaire et n'est pas la faute de la requête.
• Aucun backend sain. Un répartiteur de charge dont chaque membre échoue à sa vérification de santé n'a rien vers quoi router, et beaucoup renvoient 503 dans cet état.
• Déploiements et redémarrages. La fenêtre entre le drainage de l'ancien processus et la disponibilité du nouveau.
• Délestage délibéré. Les disjoncteurs et le contrôle d'admission renvoient 503 exprès pour protéger les parties du système qui fonctionnent encore.
• Épuisement des ressources au niveau de l'hôte. Mémoire insuffisante, descripteurs de fichiers épuisés ou disque plein, ce qui empêche le démarrage de nouveau travail.

Le schéma 503-pendant-le-déploiement

C'est le 503 le plus courant qui n'est pas un vrai incident, et il a une forme reconnaissable : une brève rafale de 503, de quelques secondes à quelques minutes, commençant exactement à une mise en production et se terminant d'elle-même. Corrélez les horodatages avec votre historique de déploiement avant d'enquêter sur autre chose.

Bien géré, un 503 de maintenance devrait :

1. Renvoyer le vrai code de statut. Une page de maintenance servie avec 200 dit aux robots d'exploration que votre contenu est maintenant un avis de maintenance, ce qui est le pire résultat possible pour une fenêtre planifiée.
2. Inclure Retry-After avec une estimation réaliste de la fenêtre.
3. Rester statique et peu coûteuse. La page de maintenance ne devrait pas dépendre de la base de données ou de l'application que vous venez de mettre hors ligne.
4. Laisser passer vos propres adresses pour que l'équipe puisse vérifier la nouvelle version avant de rouvrir.
5. Être planifié dans la surveillance comme une fenêtre de maintenance, pour qu'une panne planifiée n'alerte pas la personne d'astreinte.

La correction pour des 503 de déploiement non planifiés est une mise à jour progressive contrôlée par vérification de santé : démarrer le nouveau processus, attendre qu'il passe une vérification de disponibilité, puis drainer et arrêter l'ancien. Fait correctement, il n'y a aucune fenêtre où rien ne peut servir.

Comment corriger un 503 non planifié

1. Confirmez le code et lisez les en-têtes, y compris si un Retry-After a été envoyé et quel composant a signé la réponse :

   curl -sS -o /dev/null -D - https://example.com/

2. Écartez d'abord le mode maintenance. Vérifiez un drapeau ou fichier de maintenance resté en place après une mise en production. Cela arrive plus souvent que quiconque ne l'admet.
3. Vérifiez la santé du backend. Sur un répartiteur de charge, regardez combien de membres passent les vérifications. Zéro membre sain est une réponse immédiate.
4. Regardez la saturation. Utilisation des pools de travailleurs et de connexions, mémoire, connexions à la base de données et profondeur de file d'attente. Un 503 sous charge avec tout au plafond est une question de capacité, pas un bug.
5. Vérifiez les dépendances. Si la base de données, le cache ou une API critique est hors service, corrigez cela plutôt que la couche web.
6. Soulagez la charge, puis trouvez la cause. Monter en échelle ou relever les limites rétablit le service, mais un 503 apparu sans augmentation de trafic cache généralement une requête lente ou une fuite qui reviendra.

Les 503 aux heures de pointe et les fenêtres de maintenance planifiées

Les 503 de surcharge sont généralement intermittents longtemps avant de devenir constants, apparaissant aux heures de pointe et se résolvant d'eux-mêmes. Cette phase précoce est facile à manquer depuis un navigateur et évidente dans un relevé continu. Une vérification HTTP programmée qui affirme le code de statut attendu transforme ces échecs épars en une tendance visible avec des horaires associés, de sorte que vous puissiez agir avant que la phase intermittente ne devienne une panne. Planifier des fenêtres de maintenance dans le même outil évite que des 503 planifiés ne génèrent des alertes.