Comment résoudre l’erreur 504 Gateway Timeout (7 solutions)

Une erreur 504 Gateway Timeout se produit lorsqu’un serveur agissant comme passerelle ou proxy ne reçoit pas à temps la réponse d’un autre serveur. Elle survient souvent lorsque l’application qui traite les requêtes d’un site web est lente, surchargée ou rencontre des problèmes de connexion.

Si vous consultez un site web, essayez d’actualiser la page après quelques instants. Si vous gérez le site, commencez par examiner les journaux du serveur et de l’application pour déterminer où se produit le retard.

Voici sept méthodes pratiques pour rechercher la cause de l’erreur.

Quelles sont les causes d’une erreur 504 Gateway Timeout ?

De nombreux sites web utilisent plusieurs serveurs ou services pour traiter les requêtes.

Par exemple, un navigateur peut se connecter à Nginx ou à un CDN, qui transmet ensuite la requête à un serveur d’applications.

Si cette application met trop de temps à répondre, la passerelle peut renvoyer une erreur 504 au lieu de la page demandée.

Les causes courantes comprennent :

• Des serveurs d’applications surchargés ou qui ne répondent pas.
• Des requêtes de base de données lentes ou des appels à des API externes qui prennent trop de temps.
• Des ressources CPU ou RAM insuffisantes, ou un nombre insuffisant de processus de traitement de l’application.
• Des problèmes réseau entre la passerelle et le serveur en amont.
• Des limites de délai d’expiration du proxy ou de l’application.
• Une mauvaise configuration du CDN ou de l’infrastructure d’hébergement.

Une erreur 504 est généralement due à un problème côté serveur, même si des problèmes propres à une connexion peuvent parfois toucher certains visiteurs.

1. Actualisez le site web et vérifiez sa disponibilité

Si vous consultez simplement un site web, attendez quelques instants, puis actualisez la page.

Une surcharge temporaire du serveur ou une interruption d’une requête adressée au serveur en amont peut se résoudre sans intervention.

Vous pouvez aussi essayer un autre navigateur ou un autre réseau pour voir si le problème est propre à votre connexion.

Si l’erreur touche tout le monde, le propriétaire du site ou l’hébergeur devra généralement mener des investigations.

Évitez de soumettre plusieurs fois des paiements, des commandes ou des formulaires. Une opération peut avoir été effectuée par l’application même si le délai d’attente de la passerelle a expiré avant qu’elle ne renvoie sa réponse.

2. Consultez les journaux du serveur et de l’application

Si vous gérez le serveur, les fichiers journaux sont le meilleur point de départ.

Pour Nginx, consultez le journal des erreurs :

sudo tail -n 50 /var/log/nginx/error.log

Recherchez des messages semblables à :

upstream timed out (110: Connection timed out)

Cela indique que Nginx a attendu trop longtemps qu’une opération en amont se termine.

Examinez ensuite les journaux de l’application pour déterminer pourquoi le serveur en amont a répondu lentement.

Vous pouvez également examiner un service géré par systemd :

sudo journalctl -u myapp -n 50

Remplacez myapp par le nom réel de votre service.

3. Vérifiez l’utilisation du CPU, de la RAM et du disque

Un serveur très sollicité peut avoir du mal à traiter les requêtes avant l’expiration du délai d’attente de la passerelle.

Vérifiez la mémoire :

free -h

Vérifiez l’espace disque :

df -h

Surveillez les processus :

top

Recherchez une utilisation des ressources durablement élevée, une mémoire épuisée, des systèmes de fichiers pleins ou des processus anormalement sollicités.

Ces résultats ne prouvent pas à eux seuls la cause de l’expiration du délai d’attente de la requête, mais ils peuvent aider à repérer les goulets d’étranglement.

4. Examinez les délais d’attente de Nginx et des serveurs en amont

Si Nginx fait office de proxy inverse, vérifiez si l’application en amont répond dans les délais d’attente configurés.

Pour les serveurs en amont utilisant HTTP, la configuration peut contenir :

location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_read_timeout 60s;
}

Le paramètre proxy_read_timeout définit la durée pendant laquelle Nginx attend entre deux lectures successives de la réponse du serveur en amont, et non la durée totale de la requête.

Avant d’augmenter cette valeur, testez directement le serveur en amont :

curl --max-time 15 -i http://127.0.0.1:3000/

Remplacez l’adresse par le point de terminaison réel de votre application. Certaines routes de l’application peuvent nécessiter une authentification ou renvoyer une réponse valide autre que HTTP 200.

Si l’application elle-même est lente, augmenter le délai d’attente de Nginx risque seulement de masquer le problème sous-jacent.

Lorsqu’un délai plus long est réellement justifié, examinez également les paramètres de délai d’attente de l’application. Les applications reposant sur PHP-FPM et FastCGI utilisent d’autres directives Nginx que les serveurs en amont utilisant un proxy HTTP.

Après avoir modifié la configuration, vérifiez sa validité avant de recharger Nginx :

sudo nginx -t
sudo systemctl reload nginx

Ne rechargez Nginx que si le test de configuration réussit.

5. Vérifiez Cloudflare ou votre CDN

Si votre site web utilise Cloudflare ou un autre réseau de diffusion de contenu, déterminez si le délai d’attente expire au niveau du CDN ou de votre serveur d’origine.

Consultez les informations sur les erreurs de votre CDN et comparez-les aux journaux de votre serveur d’origine.

Une erreur 504 peut provenir d’un service en amont situé derrière votre serveur d’origine, ou d’une autre couche sur le trajet de la requête.

Cloudflare applique ses propres délais d’attente pour les connexions et les réponses. Augmenter un délai dans Nginx ne permet donc pas nécessairement de dépasser une limite imposée par le CDN.

Évitez de désactiver des fonctions de sécurité ou de mise en cache sans avoir identifié la cause de l’expiration du délai d’attente.

6. Examinez les requêtes de base de données lentes et les API externes

Parfois, le serveur web fonctionne correctement, mais l’application attend la réponse d’un autre service.

Voici quelques exemples courants :

• Une requête de base de données qui prend trop de temps.
• Une API externe qui répond lentement.
• Des pools de processus de traitement de l’application saturés.
• Des tâches en arrière-plan qui mobilisent les mêmes ressources.
• Des verrous de base de données qui retardent les requêtes.

Examinez les journaux de l’application, les journaux des requêtes lentes et les métriques des services pour repérer la source du retard.

Si une requête de base de données est en cause, examinez l’indexation, les plans d’exécution des requêtes et l’utilisation des connexions.

Pour les appels à des API externes, configurez des délais d’attente et une gestion des erreurs adaptés. Lorsque l’application le permet, il peut être préférable de traiter les tâches longues de manière asynchrone.

7. Contactez votre hébergeur

Si vous ne parvenez pas à résoudre l’erreur 504 Gateway Timeout, contactez votre hébergeur en lui transmettant les éléments que vous avez recueillis.

Indiquez le domaine concerné, le moment où le problème a commencé, s’il survient par intermittence et tout message de journal pertinent.

Signalez les modifications récentes apportées à votre application, à votre base de données, à votre CDN ou à la configuration de votre proxy inverse.

Un hébergeur peut vous aider à examiner les restrictions de ressources et les problèmes d’infrastructure auxquels vous n’avez pas accès en tant qu’administrateur.

Erreurs de passerelle 502 et 504 : quelle différence ?

Ces erreurs sont liées, mais elles signalent des problèmes différents avec un serveur en amont.

Par exemple, une application qui ferme une connexion de manière inattendue peut provoquer une erreur 502, tandis qu’une application qui met trop de temps à répondre peut entraîner une erreur 504.

Comment prévenir les erreurs 504 Gateway Timeout

Il n’est pas possible d’éviter toutes les expirations de délai d’attente, mais une bonne gestion de l’infrastructure permet de les réduire.

• Surveillez les temps de réponse de l’application et l’utilisation des ressources.
• Examinez les requêtes de base de données lentes.
• Utilisez une mise en cache adaptée pour les contenus fréquemment demandés.
• Configurez des délais d’attente appropriés pour les serveurs en amont et les applications.
• Surveillez les services en amont et la disponibilité des processus de traitement.
• Testez les changements de configuration importants avant de les déployer.

L’augmentation des délais d’attente doit être une décision réfléchie, et non la première mesure prise pour rechercher la cause du problème.

Questions fréquentes

Conclusion

Une erreur 504 Gateway Timeout signifie qu’une passerelle a attendu trop longtemps la réponse d’un serveur en amont.

Les visiteurs peuvent vérifier si le problème est temporaire, tandis que les administrateurs doivent examiner les journaux, les ressources du serveur, les performances de l’application et les paramètres du proxy.

La solution la plus fiable consiste à identifier la cause du retard plutôt qu’à augmenter les délais d’attente ou à redémarrer les services sans avoir établi de diagnostic.