Les erreurs 502, 503 et 504 ont une sémantique précise — et les confondre n’est pas qu’une imprécision de langage, c’est un retard dans le diagnostic. Ces trois codes HTTP décrivent des situations différentes, impliquent des couches différentes, et appellent des remèdes différents. Comprendre leur distinction est la base d’un debug d’infrastructure efficace.
Les couches traversées par une requête HTTP
Avant de distinguer les trois codes, il faut poser le cadre architectural. Ces erreurs n’apparaissent que dans des architectures avec au moins deux couches — un intermédiaire (reverse proxy, load balancer, CDN) et un serveur en amont. Sur un serveur unique sans intermédiaire, un 502 ou 504 ne peut pas se produire — vous obtiendrez un 500 ou une connexion refusée directement.
Dans ce schéma, le reverse proxy est le gateway mentionné dans les codes d’erreur. Quand le gateway ne reçoit pas ce qu’il attend de l’upstream, il retourne 502 ou 504 au client. Quand c’est l’upstream lui-même qui signale son indisponibilité, c’est 503.
Erreur 502 Bad Gateway — réponse invalide de l’upstream
Le code 502 signifie que le gateway (reverse proxy) a contacté l’upstream avec succès — la connexion TCP a été établie — mais a reçu une réponse invalide ou incompréhensible en retour. C’est la distinction clé avec le 504 : le 502 ne dit pas « ça a pris trop de temps », il dit « j’ai reçu quelque chose, mais ce n’était pas une réponse HTTP valide ».
// Causes typiques d'un 502 Bad Gateway
1. Process upstream mort pendant la requête
→ PHP-FPM worker crashé, Node.js process tué par OOM
→ la connexion TCP est ouverte mais la réponse est tronquée
2. Réponse HTTP malformée côté upstream
→ headers invalides, HTTP/1.1 alors que l'upstream parle HTTP/2 exclusif
→ réponse sans Content-Length ni chunked encoding
3. Upstream derrière un autre proxy avec un protocole incompatible
→ erreur de configuration de l'upstream_pass ou du proxy_pass
4. Redémarrage du service upstream pendant que des connexions sont actives
→ rolling restart non graceful, connexions coupées sans FIN/RST propre// Nginx — logs d'un 502 réel
2026/05/12 14:23:41 [error] 1234#0: *5 recv() failed (104: Connection reset by peer)
while reading response header from upstream,
client: 203.0.113.1, server: example.com,
request: "GET /api/orders HTTP/1.1",
upstream: "http://127.0.0.1:9000/api/orders"
// "Connection reset by peer" → upstream a coupé la connexion brutalement
// "recv() failed" → le proxy attendait une réponse et n'a rien reçu de valideNuance : un 502 peut être intermittent sans que le service soit « tombé ». Un PHP-FPM avec max_children trop bas crashe les workers sous charge — on obtient des 502 sporadiques pendant les pics, avec retour à la normale après. Le log applicatif révèle le crash. Le log Nginx révèle la fréquence. Les deux ensemble permettent le diagnostic.
Erreur 503 Service Unavailable — service délibérément indisponible
Le 503 est fondamentalement différent des deux autres : il est émis intentionnellement. Ce n’est pas un gateway qui échoue à joindre un upstream — c’est un service qui dit explicitement « je ne peux pas traiter cette requête maintenant ». La cause peut être une surcharge temporaire, une maintenance planifiée, ou un circuit breaker ouvert.
// Le 503 est le seul des trois à définir Retry-After
HTTP/1.1 503 Service Unavailable
Retry-After: 120 ← délai en secondes avant de réessayer
Content-Type: application/json
{ "error": "Service temporairement indisponible",
"retryAfter": 120 }
// Ou avec une date absolue
Retry-After: Mon, 12 May 2026 16:00:00 GMT// Cas d'usage légitimes du 503
// 1. Page de maintenance WordPress
wp-activate.php, mise à jour, plugin de maintenance → .maintenance créé
Nginx ou WordPress retourne 503 + Retry-After pendant la durée estimée
// 2. Circuit breaker ouvert (pattern de résilience)
if (circuitBreaker.isOpen()) {
res.status(503).set('Retry-After', '30').json({ error: 'circuit open' });
return;
}
// 3. Pool de workers épuisé — Nginx retourne 503 si l'upstream refuse
upstream backend {
server 127.0.0.1:9000;
}
→ si PHP-FPM retourne EAGAIN (queue pleine), Nginx émet un 503Le 503 est le seul de ces trois codes qui a une sémantique de recours : le client (ou le load balancer) peut légitimement réessayer après le délai indiqué. Un load balancer qui reçoit un 503 avec Retry-After peut router la requête vers une instance différente — ce que ni un 502 ni un 504 n’impliquent nécessairement.
Erreur 504 Gateway Timeout — l’upstream a mis trop de temps à répondre
Le 504 signifie que le gateway a contacté l’upstream et attendu une réponse — mais l’upstream n’a pas répondu dans le délai configuré. La distinction avec le 502 est subtile mais importante : en 502, la connexion a été établie et la réponse reçue était invalide. En 504, la connexion peut avoir été établie, mais aucune réponse n’est arrivée dans les temps.
// Causes typiques d'un 504 Gateway Timeout
1. Requête SQL lente sans index → page PHP qui "freeze" 60s+
→ Nginx timeout par défaut à 60s → 504 au client
2. Appel à une API tierce sans timeout configuré
→ le code applicatif attend indéfiniment, le proxy, lui, abandonne
3. Deadlock ou lock en attente côté base de données
→ la requête tient une transaction ouverte, en attente d'un verrou
4. Calcul synchrone trop long côté applicatif
→ génération de PDF, import CSV, resize d'image en synchrone
// Timeouts Nginx — les trois valeurs à connaître
proxy_connect_timeout 60s; ← max pour établir la connexion avec upstream
proxy_read_timeout 60s; ← max entre deux blocs de données de l'upstream
proxy_send_timeout 60s; ← max pour envoyer la requête à l'upstream
// Un 504 sur des requêtes qui prennent exactement 60s → c'est proxy_read_timeout
// Augmenter le timeout masque le problème — la vraie solution est en amontAugmenter le proxy_read_timeout pour faire disparaître un 504 est un antipattern. La bonne réponse est de comprendre pourquoi l’upstream prend plus de 60s — et de le corriger. Si l’opération est légitimement longue (export massif, traitement batch), elle doit être déportée en tâche asynchrone, pas gérée en synchrone derrière un proxy.
Quelle est la différence entre 502, 503 et 504 ?
La question la plus fréquente — et la réponse la plus utile à avoir en tête en situation de diagnostic.
| Code | Signification | Émis par | Cause racine typique | Retry automatique ? |
|---|---|---|---|---|
502 |
Bad Gateway | Gateway / proxy | Réponse invalide ou connexion coupée par l’upstream | Risqué — l’opération a peut-être abouti |
503 |
Service Unavailable | Upstream lui-même | Surcharge, maintenance, circuit breaker | Oui — après Retry-After |
504 |
Gateway Timeout | Gateway / proxy | Upstream trop lent — pas de réponse dans le délai | Risqué — l’opération est peut-être en cours |
La colonne « Retry automatique » mérite attention. Sur des opérations idempotentes (GET, PUT), retenter un 502 ou 504 est généralement sûr. Sur des opérations à effets (POST de commande, paiement), retenter sans clé d’idempotence côté serveur risque de créer des doublons — l’opération a peut-être déjà abouti avant que le proxy ne timeout.
Ce que la fréquence de ces erreurs révèle sur l’infrastructure
Un 502 ou 504 isolé est un incident. Une série de 502 ou 504 récurrents est un signal architectural. La distinction entre une anomalie ponctuelle et un symptôme structurel change complètement la réponse à apporter.
502 récurrents sous charge
Sous-dimensionnement du pool de workers applicatifs
PHP-FPM avec pm.max_children trop bas, Node.js en cluster insuffisant, Gunicorn avec trop peu de workers. Le gateway contacte l’upstream, qui a épuisé sa capacité de traitement et ferme la connexion. Solution : dimensionner le pool correctement, ajouter du monitoring sur pm.max_active_processes, et placer un backpressure explicite (503 + Retry-After) avant que les workers saturent — plutôt que de laisser le gateway retourner un 502 brutal.
504 systématiques sur des endpoints précis
Requêtes longues non déportées en tâche asynchrone
Un endpoint qui génère un rapport, exporte des données, ou effectue des opérations sur des fichiers lourds ne doit pas répondre de façon synchrone. Le pattern correct : l’endpoint accepte la demande, enqueue une tâche (Redis Queue, SQS, BullMQ), et retourne immédiatement un 202 Accepted avec un identifiant de job. Le client poll le statut séparément. Un 504 sur un endpoint de reporting est presque toujours le signe que cette séparation n’a pas été faite.
503 sans Retry-After
Service qui déleste sans signaler correctement
Un 503 sans Retry-After est une opportunité manquée. Les clients (humains ou machines) ne savent pas quand réessayer — et réessaient immédiatement, ce qui aggrave exactement la surcharge qui a causé le 503. Émettre un 503 bien formé avec un délai raisonnable est un acte de courtoisie envers les appelants et un outil de backpressure sur l’ensemble du système.
Comment émettre les bons codes côté applicatif
Le 503 est le seul de ces trois codes qu’un développeur applicatif devrait émettre délibérément. Les 502 et 504 sont la responsabilité du gateway — l’application n’a pas à les simuler. En revanche, bien émettre un 503 est une compétence.
// Node.js / Express — 503 avec backpressure
app.use((req, res, next) => {
if (server.connections > MAX_CONNECTIONS) {
res
.status(503)
.set('Retry-After', '10')
.json({
error: 'server_overloaded',
retryAfter: 10
});
return;
}
next();
});
// PHP (WordPress / plugin custom) — page maintenance avec bon code HTTP
add_action('init', function() {
if (maintenance_is_active() && !current_user_can('manage_options')) {
status_header(503);
header('Retry-After: 3600');
header('Content-Type: text/html; charset=utf-8');
include get_template_directory() . '/maintenance.php';
exit();
}
});
// Pourquoi c'est important pour le SEO
503 + Retry-After → Googlebot respecte le délai et revient plus tard
200 sur une page de maintenance → Google indexe la page de maintenance
404 sur une page en maintenance → Google désindexe l'URL définitivementCe dernier point est critique pour le SEO. Une page de maintenance qui retourne 200 ou 404 au lieu de 503 peut déclencher une désindexation ou l’indexation du contenu de maintenance. Le 503 est le seul code qui signale aux robots d’exploration « revenir plus tard, ce contenu existe toujours ».
Comment diagnostiquer un 502, 503 ou 504 en production
La séquence de diagnostic est la même pour les trois codes — ce qui change, c’est ce qu’on cherche dans les logs.
// Étape 1 — Identifier la couche qui émet l'erreur
curl -I https://example.com/endpoint
→ Regarder les headers de réponse : "Server: cloudflare" = le CDN l'émet
→ "Server: nginx" = c'est le reverse proxy
→ Headers applicatifs présents = l'application elle-même
// Étape 2 — Logs du gateway (Nginx / HAProxy)
tail -f /var/log/nginx/error.log | grep -E "upstream|connect|timeout"
// Ce qu'on cherche
"connect() failed" → upstream inaccessible → vérifier le process upstream
"Connection reset by peer" → upstream a crashé pendant la réponse → logs applicatifs
"upstream timed out" → 504 — upstream trop lent → profiler la requête lente
"no live upstreams" → tous les backends sont marqués down par le health check
// Étape 3 — Logs applicatifs
journalctl -u php8.2-fpm -n 100 --no-pager
journalctl -u node-app -n 100 --no-pager
// Ce qu'on cherche
"worker exit" → PHP-FPM worker tué (OOM, signal)
"max_children reached" → pool saturé → augmenter ou dimensionner
"Segmentation fault" → crash applicatif
// Étape 4 — État du système
free -h → mémoire disponible
uptime → load average (> nb de CPUs = problème)
ss -tlnp | grep :9000 → PHP-FPM écoute-t-il encore ?
mysqladmin status → threads connectés, queries en attenteLa règle pratique : commencer par les logs du gateway, puis remonter vers l’upstream. Le gateway voit la symptomatologie (connexion refusée, timeout, réponse invalide), les logs applicatifs révèlent la cause (crash, saturation, requête lente). Les deux ensemble donnent le diagnostic complet.
Impact des erreurs 5xx sur le référencement naturel
Google traite les erreurs 5xx différemment selon leur durée. Un 502 ou 503 ponctuel n’affecte pas le ranking — Googlebot reviendra et retentera l’exploration. Mais une série d’erreurs sur plusieurs jours commence à dégrader le crawl budget et peut signaler une instabilité structurelle au moteur d’indexation.
La Search Console Google affiche les erreurs de crawl par URL et par code d’état. Surveiller ce tableau de bord après un incident 5xx permet de quantifier l’impact et de suivre la réindexation au fur et à mesure que le service se stabilise.
Maintenance SEO-safe : pour une mise à jour WordPress avec temps d’arrêt, le schéma correct est : 1) activer la page de maintenance avec 503 + Retry-After, 2) effectuer la mise à jour, 3) désactiver la maintenance. Ne jamais retirer la page de maintenance sans avoir vérifié que le site est fonctionnel — un 200 sur une page cassée est pire qu’un 503 bien formé.
Questions fréquentes sur les erreurs 502, 503 et 504
Pourquoi est-ce que j’obtiens une erreur 502 alors que mon serveur fonctionne ?
Une erreur 502 ne signifie pas que l’ensemble du serveur est hors service — elle signifie que le reverse proxy n’a pas reçu de réponse HTTP valide de l’application. Le serveur peut être actif mais l’application (PHP-FPM, Node.js) peut avoir crashé, saturé, ou retourné une réponse malformée. Vérifier les logs PHP-FPM ou du process applicatif en priorité, pas l’état de la machine.
Une erreur 504 Gateway Timeout signifie-t-elle que mon serveur est surchargé ?
Pas nécessairement. Un 504 peut survenir même sur un serveur peu chargé si une requête spécifique est lente — requête SQL sans index, appel à une API tierce qui ne répond pas, génération de fichier volumineux. La surcharge générale du serveur est une des causes, mais la cause la plus fréquente est une requête individuelle qui dépasse le timeout configuré (souvent 60s). Identifier l’endpoint concerné avec les logs Nginx, puis profiler cette requête spécifiquement.
Est-ce que les erreurs 5xx font baisser mon référencement Google ?
Une erreur 5xx isolée n’a pas d’impact sur le SEO — Googlebot réessaie. En revanche, des erreurs 5xx sur plusieurs jours consécutifs peuvent entraîner une désindexation temporaire des pages affectées. Le signal critique est la durée, pas la présence d’une erreur. Surveiller la Search Console après un incident majeur permet de détecter les URLs que Google n’a pas pu recrawler.
Quelle est la différence entre une erreur 502 et une erreur 504 ?
Le 502 (Bad Gateway) signifie que le proxy a contacté l’upstream mais a reçu une réponse invalide — connexion coupée, réponse malformée, process crashé en cours de traitement. Le 504 (Gateway Timeout) signifie que le proxy a attendu une réponse de l’upstream mais le délai configuré s’est écoulé avant d’en recevoir une — l’upstream était trop lent. Le 502 pointe vers un problème de stabilité applicative. Le 504 pointe vers un problème de performance ou de configuration des timeouts.
Conclusion
Les erreurs 502, 503 et 504 ne sont pas interchangeables. Chacune décrit une situation précise dans la chaîne de traitement d’une requête HTTP, implique des couches différentes, et oriente vers des catégories de causes distinctes. Confondre un 504 avec un 502 en situation d’incident, c’est partir du mauvais bout du diagnostic — et perdre du temps là où il coûte le plus cher.
La séquence reste la même dans tous les cas : identifier la couche qui émet l’erreur, lire les logs dans l’ordre gateway → application → système, et remonter à la cause plutôt que de traiter le symptôme (augmenter un timeout, redémarrer le service sans comprendre pourquoi il a failli).
Ces codes HTTP sont des instruments de mesure. Un 503 bien émis avec Retry-After est un signal utile à l’ensemble de la chaîne — clients, CDN, robots de moteurs de recherche. Un 502 récurrent est une alerte sur la stabilité du pool applicatif. Un 504 systématique sur un endpoint précis est un signal architectural. Les lire correctement est la compétence de base pour gérer une infrastructure HTTP sous pression.