Comprendre les erreurs 502, 503 et 504 — et dimensionner son hébergement

Les erreurs 5xx sont les plus stressantes du web : le site est en panne, les visiteurs le voient, et le message ne dit presque rien. Pourtant 502, 503 et 504 ne racontent pas la même histoire — et savoir les distinguer fait gagner un temps précieux au moment où chaque minute compte.

L'architecture qui explique tout

Dans la quasi-totalité des hébergements modernes, une requête traverse au moins deux étages : un serveur frontal (reverse proxy : Nginx, Caddy, un load balancer, parfois un CDN) qui reçoit la requête, puis l'application (PHP-FPM, Node, conteneur…) qui la traite. Les erreurs 50x de passerelle décrivent le dialogue entre ces deux étages :

• 502 Bad Gateway — le frontal a contacté l'application, mais la réponse était invalide ou la connexion a été refusée/coupée. Traduction : l'application est plantée, redémarre en boucle, ou n'écoute pas là où le frontal la cherche.
• 503 Service Unavailable — le service se déclare indisponible : saturation assumée (file pleine, maintenance activée, autoscaling en retard). Traduction : tout fonctionne, mais il n'y a plus de place.
• 504 Gateway Timeout — l'application n'a pas répondu dans le délai imparti. Traduction : elle travaille, mais trop lentement — requête SQL interminable, appel externe qui traîne, processus saturés.

Diagnostiquer : trois questions dans l'ordre

1. L'application tourne-t-elle ? Un 502 permanent après un déploiement, c'est presque toujours un processus qui ne démarre pas (erreur de configuration, port différent, crash au boot). Les journaux de l'application — pas ceux du frontal — donnent la réponse en une minute.

2. L'erreur est-elle corrélée à la charge ? Des 503/504 aux heures de pointe ou pendant une campagne d'emailing signalent un problème de capacité : trop peu de workers, pool de connexions à la base trop petit, CPU au plafond. La corrélation se lit dans les métriques (charge, RAM, connexions) au moment exact des erreurs.

3. Qui met le temps ? Pour les 504, il faut mesurer la durée côté application (voir notre article sur le diagnostic de lenteur et l'en-tête Server-Timing). Un timeout frontal de 30 s masque souvent une requête SQL de 45 s — allonger le timeout ne « répare » rien, il déplace la file d'attente.

Dimensionner : les ordres de grandeur

Le dimensionnement se calcule, il ne se devine pas. La formule de base :

capacité (req/s) ≈ nombre de workers ÷ temps de réponse moyen (s)

Exemple : 8 workers × réponses en 200 ms → ~40 req/s soutenues.
Un pic à 60 req/s → file d'attente → latence qui grimpe → 503/504.

Trois conséquences pratiques :

• Réduire le temps de réponse augmente la capacité autant qu'ajouter des serveurs. Passer de 400 à 100 ms multiplie la capacité par quatre, à matériel constant — le cache HTTP est souvent l'anti-50x le plus rentable.
• Les limites doivent être explicites : un pool de connexions borné, des timeouts cohérents à chaque étage (frontal > application > base de données, jamais l'inverse), un plafond mémoire par conteneur. Une application sans limites ne renvoie pas de 503 propre : elle s'effondre.
• Prévoir la marge, pas l'infini : viser ~50 % d'utilisation en régime normal laisse de quoi absorber un pic ×2 sans incident. Au-delà, la question n'est plus la marge mais l'élasticité (ajout de serveurs) ou la protection (rate limiting, file d'attente).

Le cas du retour de bâton : les retries

Un piège classique aggrave les pannes : lorsque l'application ralentit, les clients (navigateurs, applications mobiles, autres services) réessaient — et doublent la charge au pire moment. Si vous contrôlez les clients, des retries avec backoff exponentiel et jitter sont indispensables ; côté serveur, un 503 avec l'en-tête Retry-After indique proprement quand revenir.

Ce qu'il faut retenir

502 : l'application ne répond pas correctement — regardez ses journaux. 503 : plus de capacité — regardez la charge et les limites. 504 : trop lent — mesurez où passe le temps. Dans les trois cas, la prévention tient en trois pratiques : des limites explicites à chaque étage, un cache qui absorbe le trafic public, et une supervision qui alerte sur la latence avant qu'elle ne devienne un timeout. Une page d'erreur soignée avec un vrai message ne répare rien, mais elle transforme une panne en incident géré — vos visiteurs font la différence.