502 Bad Gateway : ce que cela signifie réellement et comment le corriger

Vous ouvrez votre site web et, au lieu du contenu, vous voyez une page blanche indiquant 502 Bad Gateway. Cela semble inquiétant, mais dans la plupart des cas, la correction est simple. Voyons ce qui se passe et comment remettre votre site en ligne.

Que signifie réellement 502 ?

Lorsqu'un visiteur demande une page, la requête passe généralement par deux couches : un serveur web frontend (généralement Nginx) et un serveur d'application backend (PHP-FPM, Apache, Node.js ou autre). Nginx reçoit la requête, la transmet au backend et attend une réponse.

Un 502 Bad Gateway signifie que Nginx a tenté d'obtenir une réponse du backend, mais a reçu quelque chose d'invalide ou n'a reçu aucune réponse. Le backend a soit planté, soit refusé la connexion, soit renvoyé quelque chose que Nginx n'a pas pu interpréter.

info

Idée reçue fréquente : 502 ne signifie pas que votre serveur est hors service. Le serveur lui-même fonctionne bien — c'est l'application derrière Nginx qui rencontre des difficultés.

Causes les plus courantes

Le service backend s'est arrêté. C'est la raison numéro un. PHP-FPM a planté, Apache s'est bloqué ou un processus Node.js s'est arrêté silencieusement. Nginx n'a plus rien à quoi parler.

Le serveur manque de RAM. Lorsque la mémoire vient à manquer, Linux peut tuer automatiquement les processus gourmands en ressources. Ce mécanisme est appelé le OOM killer, et PHP-FPM ou MySQL en sont généralement les premières victimes. Si cela se produit régulièrement, envisagez d'ajouter un fichier swap comme filet de sécurité.

Le pool de workers PHP-FPM est épuisé. Si votre site reçoit plus de requêtes simultanées que PHP-FPM ne peut en traiter, les nouvelles requêtes s'accumulent dans la file d'attente et finissent par expirer. Cela se produit souvent lorsque des robots de moteurs de recherche explorent votre site de manière trop agressive — nous avons expliqué comment gérer cela dans notre guide de blocage des bots.

Socket ou port mal configuré. Nginx s'attend à trouver PHP-FPM sur un socket Unix ou un port TCP spécifique. Si le chemin dans la configuration Nginx ne correspond pas à la configuration PHP-FPM, vous verrez des erreurs 502 immédiatement après toute modification.

Comment le diagnostiquer

Pour effectuer les étapes suivantes, connectez-vous à votre serveur via SSH. Vous pouvez apprendre à le faire dans notre article sur SSH.

Étape 1. Vérifiez si le backend fonctionne

Vérifiez l'état de votre service backend :

sudo systemctl status php8.2-fpm

Remplacez php8.2-fpm par votre version réelle de PHP ou le nom de votre service backend. Si la sortie indique inactive (dead) ou failed, c'est là le problème. Redémarrez-le :

sudo systemctl restart php8.2-fpm

Vérifiez ensuite à nouveau l'état pour vous assurer qu'il a bien démarré.

Étape 2. Vérifiez le journal d'erreurs Nginx

Le journal d'erreurs vous indique presque toujours exactement ce qui s'est mal passé :

sudo tail -30 /var/log/nginx/error.log

Si vous utilisez FASTPANEL®, vous pouvez également consulter les journaux directement dans l'interface web : ouvrez la fiche du site, allez dans la section "Logs" et vérifiez l'onglet "Frontend Error Log".

Voici les messages d'erreur les plus courants et leur signification :

connect() failed - Connection refused - le service backend n'est pas en cours d'exécution. Redémarrez-le comme indiqué à l'étape 1.

connect() failed - No such file or directory - Nginx tente d'atteindre un socket Unix qui n'existe pas. Vérifiez que le chemin du socket dans votre configuration Nginx correspond à ce que PHP-FPM crée réellement.

upstream sent too big header - le backend a renvoyé des en-têtes HTTP trop volumineux pour le tampon par défaut. Ajoutez ces lignes à la configuration de votre site Nginx à l'intérieur du bloc server :

fastcgi_buffers 16 16k;
fastcgi_buffer_size 32k;

Après modification, testez la configuration et rechargez Nginx :

sudo nginx -t && sudo systemctl reload nginx

Étape 3. Vérifiez les ressources du serveur

free -h

Si la colonne available affiche moins de 100-200 MB de mémoire libre, votre serveur est probablement à court de RAM. Vérifiez ce qui la consomme :

ps aux --sort=-%mem | head -10

attention

Si la pression mémoire est la cause profonde, la solution temporaire la plus rapide consiste à ajouter un fichier swap. Cependant, le swap sur disque est bien plus lent que la RAM et ne doit pas être considéré comme une solution permanente. Si votre serveur manque régulièrement de mémoire, il est temps soit d'optimiser vos applications, soit de passer à une offre avec plus de RAM.

Conclusion

Une 502 Bad Gateway est presque toujours un problème de backend — un service qui a planté, des workers épuisés ou une mémoire insuffisante. Vérifiez l'état du backend, consultez le journal d'erreurs Nginx et examinez votre utilisation des ressources. Dans la très grande majorité des cas, vous trouverez la réponse en quelques minutes.

Si vous préférez ne pas gérer cela seul, chez kodu.cloud, nous fournissons une assistance technique gratuite 24 h/24 et 7 j/7 avec chaque VPS et serveur dédié. Tous nos clients bénéficient également de FASTPANEL® Extended sans coût supplémentaire, ce qui facilite considérablement l'analyse des journaux et la gestion des services via une interface web.