Quand un site renvoie soudain 502 ou 504, les visiteurs ne voient qu'une ligne d'erreur. Ces deux codes se situent presque toujours « entre le reverse proxy (Nginx par exemple) et l'application back-end ». Ce guide vous aide à localiser le problème rapidement.
1. 502 ou 504
- 502 Bad Gateway : lorsque Nginx transmet la requête au back-end, celui-ci ne répond pas, a planté, ou est injoignable.
- 504 Gateway Timeout : le back-end répond, mais trop lentement, au-delà du délai d'attente.
2. Causes les plus fréquentes
- Le back-end (Node, PHP-FPM, Python, etc.) a planté ou n'a jamais démarré.
- Le port ou l'adresse de proxy_pass dans Nginx est erroné, ou le back-end a changé de port.
- Back-end lent (requêtes lentes, boucles infinies, API externes en timeout) → 504.
- Mémoire épuisée et processus tué par l'OOM killer du système.
3. Démarche de diagnostic
- Le back-end tourne-t-il ? Utilisez pm2 list ou systemctl status SERVICE pour le vérifier.
- Vérifiez le port : ss -lntp pour voir si le back-end écoute bien sur le port vers lequel Nginx transmet.
- Lisez le journal d'erreurs Nginx : tail -f /var/log/nginx/error.log — il précise s'il s'agit d'un refus de connexion ou d'un timeout.
- Interrogez le back-end en local : curl http://127.0.0.1:PORT — si cela fonctionne, le problème vient de la configuration Nginx ; sinon, c'est le back-end lui-même.
4. Correctifs correspondants
- Back-end à l'arrêt → relancez le processus et cherchez la cause du plantage dans ses journaux.
- Mauvais port → corrigez proxy_pass dans Nginx, puis nginx -t et reload.
- Lenteur en 504 → optimisez la requête ou l'API lente, ou augmentez proxy_read_timeout (solution de contournement).
- OOM → ajoutez du swap ou augmentez la RAM (voir l'article « Mémoire insuffisante (OOM) » du centre d'aide).