Une erreur 504 Gateway Timeout signifie qu’un serveur jouant le rôle de passerelle ou de proxy a attendu la réponse du serveur situé derrière lui, puis a abandonné. La requête a atteint votre CDN, votre répartiteur de charge ou votre serveur web, a été transmise à l’application, et celle-ci n’a pas répondu avant l’expiration du délai.
Le serveur derrière le proxy tourne souvent toujours. Il est simplement trop lent, ou c’est ce qu’il attend qui l’est. C’est ce qui distingue une 504 de la plupart des pannes : redémarrer les services la règle rarement durablement. Ce guide explique comment identifier le délai qui a expiré, ce qui ralentit généralement la requête et comment traiter la cause plutôt que le symptôme.
Ce que vous apprend une 504
Une requête vers un site web moderne traverse plusieurs couches, et chacune fixe sa propre limite d’attente envers la suivante :
Un CDN comme Cloudflare attend votre serveur d’origine pendant une durée fixe.
Un répartiteur de charge applique un délai d’inactivité ou de réponse par cible.
nginx attend le serveur amont selon proxy_read_timeout ou fastcgi_read_timeout, 60 secondes par défaut.
L’application a ses propres limites, comme max_execution_time en PHP ou le délai des workers dans Gunicorn.
La 504 provient de la première couche dont la limite est atteinte. Ses voisines signifient autre chose : une 502 Bad Gateway indique que le serveur amont a renvoyé une réponse invalide ou n’a pas répondu du tout, et une 503 Service Unavailable que le service a refusé la requête parce qu’il est surchargé ou en maintenance.
Identifier le délai qui a expiré
Chronométrez la requête. Une 504 qui arrive toujours après le même nombre de secondes désigne une limite précise :
curl -s -o /dev/null -w « status %{http_code} after %{time_total}s\n » https://www.example.com/reports
status 504 after 60.04s
Examinez ensuite les en-têtes de réponse et la page d’erreur pour savoir quelle couche a répondu, comme pour toute erreur 5xx. Une page nginx basique avec server: nginx signifie que votre propre serveur web a expiré. Une page aux couleurs du CDN qui mentionne votre hôte signifie que le CDN a expiré en attendant votre serveur d’origine.
nginx consigne l’expiration avec l’adresse qu’il attendait :
upstream timed out (110: Connection timed out) while reading response header from upstream,
upstream: « fastcgi://unix:/run/php/php8.3-fpm.sock », request: « GET /reports HTTP/2.0″
Vous savez maintenant quelle page est lente et quelle partie de la stack l’a fait attendre. Reste à comprendre pourquoi.
Causes fréquentes et solutions
Requêtes de base de données lentes
C’est la cause la plus fréquente. Une requête qui prenait 50 millisecondes avec mille lignes en prend 40 avec un million, parce qu’elle parcourt toute la table. Activez le journal des requêtes lentes et cherchez celles de la page :
# MySQL / MariaDB
SET GLOBAL slow_query_log = ‘ON’;
SET GLOBAL long_query_time = 1;
# PostgreSQL, in postgresql.conf
log_min_duration_statement = 1000
Exécutez la requête la plus lente avec EXPLAIN et repérez les parcours complets de table. Ajouter l’index manquant suffit généralement. Les verrous sont l’autre suspect habituel : une longue transaction ou une migration peut bloquer une table pendant que toutes les requêtes qui en ont besoin attendent.
API externes lentes
Les pages appellent souvent d’autres services pendant leur génération : un prestataire de paiement, un calculateur de frais de port, un moteur de recherche, un CRM. Si ce service est lent, votre page l’est aussi, et votre proxy expire. Fixez un délai court sur chaque appel sortant, quelques secondes plutôt que la valeur par défaut de la bibliothèque, et décidez de ce que la page affiche quand l’appel échoue. Des frais de port « calculés lors du paiement » valent mieux qu’une 504.
Gardez un œil sur les services dont vous dépendez. La surveillance des services tiers d’Uptimecheck suit les pages de statut de 31 services comme Klarna, Shopify et Cloudflare : un prestataire lent apparaît ainsi à côté de vos propres vérifications.
Trop peu de workers pour le trafic
Quand tous les workers sont occupés, les nouvelles requêtes attendent dans une file. Elles ne sont pas lentes en soi, elles attendent leur tour, et le chronomètre du proxy tourne pendant tout ce temps. PHP-FPM le signale dans son journal avec server reached pm.max_children. Ajouter des workers n’aide que si le serveur dispose de la mémoire et du CPU nécessaires. La meilleure solution consiste souvent à raccourcir chaque requête, pour que les mêmes workers en traitent davantage, et à mettre en cache les pages qui ne varient pas d’un visiteur à l’autre.
Des tâches longues dans une requête web
Exports, imports, génération de rapports, traitement d’images ou envoi de centaines d’e-mails n’ont rien à faire dans une requête web. Ils durent le temps qu’il faut, et tôt ou tard l’un d’eux dépasse un délai. Déplacez-les dans une file d’attente en arrière-plan : la requête lance la tâche et répond aussitôt, puis la page interroge régulièrement le résultat, ou l’utilisateur reçoit un e-mail une fois la tâche terminée.
Le serveur lui-même est surchargé
Un CPU saturé, une pression mémoire qui pousse le serveur à swapper ou un disque qui ne suit pas ralentissent tout en même temps. Une 504 sur toutes les pages, et pas seulement sur une, oriente vers cette piste. Examinez le CPU, la mémoire, le swap et l’attente disque sur la même période :
uptime
free -m
iostat -x 5 3
La surveillance des serveurs conserve cet historique : vous voyez ce que faisait le serveur à la minute où les 504 ont commencé, au lieu de deviner après coup.
Problèmes réseau entre les couches
Si le proxy ne parvient pas du tout à joindre le serveur amont, par exemple parce qu’un pare-feu ignore les paquets au lieu de les rejeter, la connexion reste bloquée jusqu’à expiration. Le résultat est alors une 504 plutôt qu’une 502. Vérifiez que le proxy peut ouvrir une connexion vers l’adresse et le port du serveur amont depuis la même machine.
Quand augmenter le délai est justifié
Certaines requêtes sont légitimement longues : un gros envoi de fichier, un rapport qu’un administrateur demande une fois par mois. Augmentez alors la limite pour ce chemin uniquement, et respectez l’ordre des couches, pour que les couches externes attendent plus longtemps que les couches internes :
location /admin/exports/ {
proxy_read_timeout 300s;
proxy_pass http://app;
}
Augmenter la limite pour tout le site ne corrige pas les pages lentes. Les visiteurs attendent simplement plus longtemps avant de voir une erreur, et les requêtes lentes monopolisent les workers plus longtemps, ce qui allonge la file pour tous les autres.
Comment la surveillance détecte les 504
Une 504 surgit rarement de nulle part. La page ralentit un peu chaque semaine à mesure que les données augmentent, jusqu’au jour où elle franchit la limite. C’est plutôt une bonne nouvelle : vous pouvez la voir venir.
Surveillez le temps de réponse, pas seulement le statut. Uptimecheck enregistre le temps de réponse de chaque vérification, décomposé en DNS, connexion, TLS, serveur et téléchargement : vous voyez si c’est le serveur ou le réseau qui a ralenti. Une alerte de réponse lente vous prévient quand une page dépasse la limite que vous avez fixée, bien avant le délai du proxy. Notre guide sur ce qu’est un bon temps de réponse vous aide à choisir cette limite.
Confirmez les échecs avant d’alerter. Les vérifications s’exécutent jusqu’à chaque minute depuis Stockholm, Londres et New York, et chaque échec est confirmé depuis un second emplacement : une seule requête lente ne réveille personne.
Surveillez directement les pages lentes. La recherche, le paiement, les pages de compte et les rapports sont là où surviennent les 504, rarement sur la page d’accueil. Ajoutez des moniteurs de disponibilité pour ces pages, avec un délai qui correspond à ce qu’un visiteur est prêt à tolérer.
Checklist 504
Chronométrez la requête : un nombre rond de secondes révèle la limite qui a expiré.
Lisez les en-têtes et la page d’erreur pour savoir quelle couche a expiré.
Repérez la page lente dans le journal d’erreurs du proxy.
Cherchez les requêtes lentes, les verrous et les appels externes lents de cette page.
Vérifiez les workers, le CPU, la mémoire, le swap et le disque sur les mêmes minutes.
Corrigez la partie lente, mettez-la en cache ou déplacez-la dans une tâche en arrière-plan.
N’augmentez les délais que pour les chemins légitimement longs, les couches externes plus longues que les couches internes.
Alertez sur les réponses lentes, pour repérer la prochaine 504 tant qu’elle n’est encore qu’un ralentissement.