504 Gateway Timeout

Ce que signifie cette erreur et comment la reconnaître

• Le navigateur affiche 504 Gateway Timeout après avoir attendu, au lieu d’échouer immédiatement.
• Les rapports, imports groupés, exports, traitements d’images ou recherches complexes échouent alors que les pages simples continuent de fonctionner.
• Les échecs deviennent plus fréquents lorsque l’application est très sollicitée ou que les requêtes sont mises en file d’attente.
• Le backend répond lorsqu’il est testé directement, mais la même requête expire via un proxy, un CDN ou un load balancer.
• Les logs de la gateway indiquent qu’une requête upstream a duré longtemps avant le renvoi de l’erreur 504.
• L’application peut continuer le traitement après que le navigateur a reçu le timeout, ce qui peut laisser des tâches en double ou abandonnées si l’action est relancée.

Causes principales, classées par probabilité

1. Requêtes lentes ou bloquées vers la base de données : des index manquants, des tables qui grossissent, des requêtes inefficaces et des conflits de verrous peuvent faire attendre l’application au-delà de la limite de la gateway.
2. Surcharge ou mise en file d’attente du backend : les requêtes peuvent attendre des workers applicatifs, des connexions à la base de données, du CPU, de la mémoire ou d’autres ressources limitées.
3. Opération synchrone réellement longue : les exports, imports, rapports ou traitements de fichiers volumineux peuvent être légitimes, mais inadaptés à une requête de page classique.
4. API downstream ou webhook lent : l’application peut attendre un autre service avant de pouvoir répondre.
5. Timeouts restrictifs du proxy ou du serveur : Nginx, Apache, un CDN ou un load balancer peut cesser d’attendre avant la fin du traitement de l’application.
6. Problèmes réseau entre les couches de gateway : la latence, la perte intermittente de paquets ou les problèmes de routage sont plus plausibles dans les déploiements multi-serveurs ou multi-régions, en particulier lorsque le temps de traitement de l’application n’explique pas le délai.

Comment corriger le problème

1. Identifier la requête en échec et sa durée

Consultez les logs d’accès de la gateway et de l’application pour trouver la requête à l’origine de l’erreur 504. Notez la route ou l’action utilisateur, l’horodatage, la durée de réponse, le statut et indiquez si toutes les requêtes échouent ou si une seule opération est concernée.

Si seuls les rapports, imports, exports ou recherches complexes échouent, commencez par examiner cette opération plutôt que de considérer l’incident comme une panne complète du serveur.

2. Comparer le backend avec l’ensemble du chemin de requête

Avec l’autorisation nécessaire et une requête de test sûre, comparez le temps de réponse direct du backend avec celui de la même requête via le proxy, le CDN ou le load balancer.

• Une réponse lente en accès direct comme via la gateway indique plutôt un problème lié à l’application, à la base de données, à la capacité ou à une dépendance.
• Une réponse directe rapide, mais une requête proxy qui échoue, indique plutôt un timeout d’intermédiaire, un problème de routage ou un problème réseau entre la gateway et le backend.

Ne contournez pas les contrôles d’accès de production et n’envoyez pas une requête qui modifie l’état uniquement à des fins de test.

3. Examiner le temps d’exécution de la base de données et les attentes liées aux verrous

Activez ou consultez les diagnostics des requêtes lentes et des attentes liées aux verrous de la base de données, conformément aux recommandations opérationnelles de votre plateforme de base de données. Recherchez les requêtes dont la durée approche ou dépasse le timeout actif de la gateway.

Vérifiez les index manquants, les jointures ou filtres inefficaces, la croissance des tables et les conflits de verrous. Optimisez la requête, réduisez le volume de données traité ou ajoutez un index uniquement après avoir confirmé qu’il corrige le goulot d’étranglement mesuré. Coordonnez les modifications de schéma ou d’index avec le responsable de la base de données, car elles peuvent consommer des ressources et affecter les charges concurrentes.

N’augmentez pas simplement le timeout pour dissimuler une requête qui devrait s’exécuter rapidement.

4. Vérifier la capacité du backend et les files d’attente

Examinez les métriques de l’application, du serveur web et du système afin de détecter l’épuisement des workers, les requêtes en attente, les limites de connexions à la base de données, la pression sur le CPU ou la mémoire et les autres contraintes de ressources présentes pendant l’échec.

Si les requêtes attendent que des ressources deviennent disponibles, corrigez ce goulot d’étranglement avant d’allonger les timeouts. Modifier la capacité ou les paramètres des processus peut affecter la stabilité du service ; effectuez donc ces changements avec l’autorisation opérationnelle et selon le processus de changement applicables.

5. Déplacer les traitements longs vers une tâche en arrière-plan

Pour les imports, exports, générations de rapports, traitements d’e-mails et tâches similaires, utilisez une tâche en arrière-plan lorsque l’application le permet. La requête initiale doit démarrer ou mettre en file le traitement, tandis qu’une vue d’état distincte ou une notification indique la progression et la fin de l’opération.

Cela évite de maintenir ouverts une connexion du navigateur, un worker de la gateway et une requête applicative pendant toute la durée de l’opération. Vérifiez que la tâche gère correctement les nouvelles tentatives et les soumissions en double avant d’adopter ce modèle.

6. Examiner attentivement les paramètres de timeout de Nginx

Si Nginx est la gateway, examinez les paramètres proxy_read_timeout et proxy_connect_timeout applicables dans le bloc server ou location concerné. Confirmez quelle couche applique le timeout avant de modifier quoi que ce soit.

Augmentez un timeout uniquement lorsque l’opération est censée durer plus longtemps, que le backend est sain et que la consommation supplémentaire de connexions et de workers est acceptable. Les modifications de configuration nécessitent l’autorisation appropriée. Après avoir enregistré la modification, validez la configuration et rechargez Nginx selon votre procédure normale de déploiement, puis répétez l’opération qui échouait auparavant. Ne combinez pas le rechargement d’un service avec des diagnostics en lecture seule dans le cadre d’un changement non planifié.

7. Examiner les paramètres du proxy Apache

Pour Apache utilisant mod_proxy, examinez les paramètres Timeout et ProxyTimeout applicables. Si des uploads volumineux sont concernés, examinez également le comportement pertinent de mod_reqtimeout.

Lorsque cela est possible, appliquez la modification sûre la plus ciblée à la route ou à l’opération concernée, avec une autorisation et un plan de retour arrière. Effectuez un nouveau test avec la même requête et vérifiez que les attentes prolongées n’épuisent pas les workers ou les connexions.

8. Vérifier le comportement du CDN et du load balancer

Si le site utilise Cloudflare ou un autre CDN ou load balancer, examinez le timeout de gateway, le routage vers l’origine, l’état de santé et la configuration associée au plan de ce service. Un intermédiaire peut appliquer une limite impossible à augmenter dans la configuration disponible.

Lorsque l’origine nécessite plus de temps que cette limite, optimisez l’opération ou déplacez-la vers un traitement asynchrone plutôt que de compter sur une requête du navigateur plus longue.

9. Isoler les appels tiers lents

Mesurez séparément chaque appel à une API externe ou à un webhook. Définissez, lorsque cela est possible, un timeout interne plus court pour une dépendance, gérez explicitement l’échec et renvoyez un état en attente ou permettant une nouvelle tentative lorsque le traitement peut se terminer ultérieurement.

Évitez qu’une dépendance peu fiable consomme l’intégralité du timeout de la gateway. Vérifiez que les nouvelles tentatives sont limitées et sûres avant d’ajouter un mécanisme automatique de retry.

10. Vérifier la correction

Répétez exactement l’action de la page ou la requête qui échouait auparavant. Confirmez qu’elle se termine dans le délai du timeout actif de la gateway et examinez ensuite les logs pour vous assurer que le backend n’accumule pas de traitements abandonnés, en double ou anormalement longs. Effectuez le test via l’ensemble du chemin de production, et pas uniquement directement contre le backend.

Prévention et vérification du correctif

• Utilisez des tâches en arrière-plan pour les imports, exports, générations de rapports, traitements d’e-mails et autres opérations susceptibles de dépasser la durée d’une requête de page classique.
• Examinez les index et les plans d’exécution des opérations de base de données associées aux pages qui expirent fréquemment, à mesure que les données augmentent.
• Surveillez séparément la durée des requêtes, le temps en file d’attente, le temps de base de données, l’utilisation des workers et le temps des dépendances.
• Définissez délibérément les timeouts du proxy et de l’application en fonction de l’opération légitime la plus lente, tout en limitant les timeouts des dépendances tierces.
• Testez les opérations critiques via l’ensemble du chemin de production, y compris le CDN ou le load balancer, et pas uniquement contre l’origine.
• Concevez les retries et les soumissions répétées de manière sûre afin qu’un timeout de gateway ne crée pas de tâches ou de transactions en double.
• Après une modification, répétez exactement l’opération qui a expiré et vérifiez qu’elle se termine sans accumulation excessive de travail en file d’attente.

Questions fréquentes