Erreur 504 Gateway Timeout : comment la diagnostiquer et la corriger

L’erreur 504 Gateway Timeout survient lorsque le serveur proxy (Nginx, Apache, load balancer) n’obtient pas de réponse à temps du serveur applicatif ou de la base de données.
C’est une erreur frustrante car elle touche souvent les sites à fort trafic ou les applications mal optimisées.

Dans cet article, nous allons explorer les causes principales et les solutions concrètes pour corriger une erreur 504.

Plan de l’article

• Qu’est-ce qu’une erreur 504 Gateway Timeout ?
• Différence entre 502 et 504
• Causes fréquentes côté backend
• Causes liées à la configuration du proxy
• Étapes de diagnostic pas à pas
• Solutions pratiques
• Bonnes pratiques pour éviter l’erreur 504

Qu’est-ce qu’une erreur 504 Gateway Timeout ?

Le code HTTP 504 signifie que le serveur proxy a attendu trop longtemps une réponse du serveur en amont.
Contrairement au 502 Bad Gateway (réponse invalide du backend), le 504 indique une absence totale de réponse dans le délai imparti.

Différence entre 502 et 504

• 502 Bad Gateway : Nginx reçoit une réponse invalide du backend.
• 504 Gateway Timeout : Nginx n’a reçu aucune réponse dans le temps imparti.

Causes fréquentes côté backend

• Processus PHP-FPM, Node.js ou Python trop lents.
• Requêtes SQL très lourdes → base de données saturée.
• Boucles infinies ou blocages applicatifs.
• Backend arrêté ou en surcharge CPU/RAM.

Causes côté proxy (Nginx / Apache)

• Timeouts trop courts dans la configuration (proxy_read_timeout, fastcgi_read_timeout).
• Load balancer mal configuré.
• Réseau saturé ou instable entre proxy et backend.
• Trop de connexions simultanées.

Diagnostic pas à pas

1. Vérifier les logs Nginx :

tail -f /var/log/nginx/error.log

2. Vérifier la santé du backend :

systemctl status php8.2-fpm

3. Tester directement le backend :

curl -I http://127.0.0.1:9000

4. Augmenter temporairement le timeout :

proxy_read_timeout 180;
fastcgi_read_timeout 180;

Solutions pratiques

• Optimiser les requêtes SQL et le code applicatif.
• Augmenter les valeurs proxy_read_timeout et fastcgi_read_timeout.
• Vérifier la charge serveur (CPU/RAM) et adapter les ressources.
• Mettre en place un système de cache (Redis, Varnish).
• Répartir la charge avec un load balancer ou des workers supplémentaires.

Exemple Nginx :

location ~ \.php$ {
    include fastcgi_params;
    fastcgi_pass unix:/run/php/php8.2-fpm.sock;
    fastcgi_index index.php;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    fastcgi_read_timeout 180;
}

Bonnes pratiques pour éviter l’erreur 504

• Mettre en place un monitoring des temps de réponse.
• Activer l’auto-restart pour les services backend (Restart=always).
• Utiliser un CDN ou un reverse proxy pour réduire la charge.
• Optimiser la base de données et les index.
• Effectuer régulièrement des tests de charge (stress tests).

Conclusion

Une erreur 504 Gateway Timeout est généralement le signe d’un backend trop lent ou surchargé.
En combinant diagnostic précis, optimisation applicative et ajustement des timeouts, il est possible de corriger rapidement ce problème.

Avec une bonne stratégie de prévention (cache, monitoring, scaling), vous éviterez qu’il ne réapparaisse en production.