Loading...

Erreurs HTTP

504 Gateway Timeout : qui a attendu, combien de temps, et comment le corriger

Un 504 est un problème d'attente, pas une connexion cassée. Un proxy placé devant votre site a demandé une page à votre serveur, a attendu aussi longtemps qu'il y était autorisé, puis a abandonné. Ce guide montre comment savoir qui attendait qui, quel délai a expiré en premier, et comment corriger la partie lente au lieu de la masquer.

9 min de lecture Intermédiaire Mis à jour

504 Gateway Timeout : qui a attendu, combien de temps, et comment le corriger

Ce que dit réellement un 504

Une passerelle est tout ce qui reçoit une requête et la transmet : une périphérie CDN, un répartiteur de charge, un nginx devant PHP-FPM ou Node. 504 Gateway Timeout, c'est la passerelle qui dit : j'ai joint le serveur derrière moi, je lui ai demandé, et la réponse n'est pas arrivée avant ma limite.

C'est ce qui distingue le 504 de ses voisins. Un 502 Bad Gateway signifie que la réponse était inutilisable ou que la connexion a échoué. Un 503 Service Unavailable signifie que quelque chose a refusé la requête volontairement. Un 504 signifie que personne n'a rien refusé — la requête a été acceptée, et elle peut très bien tourner encore sur votre serveur après que le visiteur a vu l'erreur.

Ce dernier point compte en pratique. Un 504 n'annule pas le travail : un rapport qui a expiré au niveau du proxy peut se terminer sur l'origine une minute plus tard, et un visiteur qui clique à nouveau lance une deuxième copie.

Qui attend qui

Une requête typique traverse plusieurs points d'attente : visiteur → périphérie CDN → votre serveur web (nginx ou Apache) → votre application (PHP-FPM, Node, un conteneur) → votre base de données ou une API externe. Chaque flèche est une passerelle avec son propre délai, réglé indépendamment, souvent par des personnes différentes.

La règle qui fait gagner le plus de temps : le délai le plus court de la chaîne est celui qui se déclenche. Si la périphérie attend 60 secondes, que votre nginx attend 60 secondes PHP-FPM et que PHP arrête un script après 30, la requête n'approche jamais la limite de la périphérie — PHP y met fin à 30 secondes et le maillon au-dessus signale l'échec.

La première question n'est donc pas « pourquoi le CDN expire-t-il » mais combien de temps s'est écoulé avant l'apparition de l'erreur ? Un 504 à presque exactement 60 secondes pointe vers une limite de 60 secondes ; à 30 secondes, vers une limite de 30 secondes. Comparez ce chiffre aux limites que vous connaissez, et le maillon qui a abandonné se désigne généralement de lui-même.

Les causes derrière presque tous les 504

Une requête lente. Une requête sans le bon index, qui parcourt une table passée de dix mille à dix millions de lignes. Elle était rapide au lancement, elle est lente aujourd'hui, et rien n'a changé dans le code.

Un travail long par nature. Exports CSV et Excel, rapports PDF, imports en masse, traitement d'images ou de vidéos, une sauvegarde lancée depuis une page d'administration. Ce ne sont pas des bugs ; ce sont des tâches qui n'ont pas leur place dans une requête web.

Un appel externe sans délai. Un prestataire de paiement, une API de livraison, un service de recherche. Quand il se bloque, votre requête se bloque avec lui, et vos visiteurs subissent la panne de quelqu'un d'autre.

Une origine surchargée. Quand chaque worker ou thread PHP-FPM est occupé, les nouvelles requêtes attendent dans une file avant même de démarrer. Chaque requête peut être rapide ; c'est l'attente dans la file qui épuise le délai. Ces 504 se concentrent aux pics de trafic.

Un problème réseau entre deux maillons. Un pare-feu qui abandonne silencieusement les paquets au lieu de les refuser fait attendre le proxy une connexion qui ne s'ouvrira jamais. Le résultat est un 504 plutôt qu'un échec immédiat.

Diagnostiquer : mesurer où part le temps

Chronométrez la requête via le CDN, puis la même requête directement vers votre origine. curl peut découper le temps en phases, comme dans les commandes ci-dessous.

Si connect est élevé ou n'aboutit jamais, le problème est l'accès à l'origine : un pare-feu, le routage, un serveur arrêté. Si connect est rapide et que ttfb (time to first byte) est long, l'origine a accepté la requête et y travaille encore — le 504 classique, dont la réponse se trouve dans votre application.

La deuxième commande contourne le CDN avec --resolve tout en envoyant votre nom d'hôte. Si l'origine seule met aussi 70 secondes, la périphérie dit la vérité. Si elle répond en deux secondes en direct mais expire via le CDN, cherchez ce qui diffère : une règle de pare-feu, un autre backend pour ce nom d'hôte, ou des en-têtes que votre application traite autrement.

Lisez ensuite les journaux de l'origine pour ce moment précis. Dans nginx, ajoutez $request_time et $upstream_response_time au format de journal ; dans Apache, %D. Activez le journal des requêtes lentes de votre base de données et, pour PHP, le slowlog de PHP-FPM, qui écrit une trace d'appels pour chaque requête trop longue — en général le chemin le plus court vers la ligne exacte.

Chronométrer une requête via le CDN puis directement vers l'origine

# through the CDN
curl -o /dev/null -s -w 'connect=%{time_connect}s tls=%{time_appconnect}s ttfb=%{time_starttransfer}s total=%{time_total}s code=%{http_code}\n' \
  https://www.example.com/reports/export

# straight to the origin, same hostname
curl -o /dev/null -s -w 'connect=%{time_connect}s ttfb=%{time_starttransfer}s total=%{time_total}s code=%{http_code}\n' \
  --resolve www.example.com:443:ORIGIN_IP https://www.example.com/reports/export

Corrigez d'abord la partie lente

Allonger un délai fait disparaître l'erreur, mais le visiteur attend tout aussi longtemps. Avant de toucher à une limite, raccourcissez la requête.

Indexer et mettre en cache. Repérez la requête lente dans le journal des requêtes lentes et ajoutez l'index dont elle a besoin. Mettez en cache les résultats que de nombreux visiteurs partagent, dans l'application ou en périphérie avec les en-têtes Cache-Control.

Sortir le travail long de la requête. Transformez un export en tâche d'arrière-plan : le clic met la tâche en file et rend la main aussitôt, la page affiche la progression, et le fichier terminé arrive sous forme de lien de téléchargement ou par e-mail. La requête web reste courte, quelle que soit la taille de la tâche.

Donner à chaque appel externe son propre délai. Quelques secondes, avec un repli raisonnable, pour que la panne d'une autre entreprise ne devienne pas la vôtre.

Dimensionner l'origine pour le pic. Si les 504 se concentrent aux heures chargées, ajoutez des workers (pm.max_children de PHP-FPM, processus Node, réplicas de conteneurs) et laissez le cache de la périphérie absorber les requêtes répétées pour que moins d'entre elles atteignent l'origine.

N'allongez le délai que là où c'est justifié

Certaines requêtes sont longues par conception : un gros upload en cours de traitement, un rapport impossible à découper, une API qui diffuse ses résultats en flux. Pour celles-là, allongez la limite — uniquement pour ce chemin, et à chaque maillon.

Sur cdn.com.tr, c'est un réglage de règle de diffusion : Délai de réponse de l'origine (secondes), de 1 à 3 600 secondes par règle, 60 secondes par défaut. Créez une règle séparée pour le chemin concerné, par exemple /admin/export/, et donnez un délai plus long à cette règle seule. Le reste du site garde le délai court par défaut et échoue toujours vite quand quelque chose ne va vraiment pas. Sur le domaine d'une application Managed Container, le délai par défaut est de 300 secondes, sauf si la règle en définit un autre.

Le délai compte le temps entre deux morceaux de données venant de votre origine, pas la durée totale de la requête. Tant que des données circulent, la périphérie garde la requête ouverte. C'est pourquoi une réponse en flux — un CSV écrit ligne par ligne, un flux de progression — peut durer de nombreuses minutes, alors qu'un script qui calcule pendant cinq minutes puis affiche tout d'un coup ne le peut pas.

Alignez ensuite les maillons derrière la périphérie : proxy_read_timeout ou fastcgi_read_timeout de nginx, max_execution_time de PHP, la limite propre à votre serveur d'application. Un chemin n'est jamais plus long que sa limite la plus courte.

Quand un CDN est placé devant

Un CDN change ce que vous coûte un 504.

Les pages en cache continuent d'être servies. Sur une règle qui met en cache, si votre origine expire alors que la périphérie conserve une copie de la page — même périmée — la périphérie sert cette copie au lieu de l'erreur. Une minute lente sur l'origine devient une page légèrement périmée plutôt qu'une page cassée. C'est une bonne raison de mettre en cache tout ce qui peut l'être, avec des TTL qui correspondent à la fréquence réelle de changement du contenu.

Les chemins lents deviennent visibles. Quand les 504 n'apparaissent que sur /search ou /checkout — les chemins dynamiques, non mis en cache —, vous savez exactement où regarder.

Les connexions longues suivent la même règle. Une connexion WebSocket qui n'envoie rien pendant plus longtemps que le délai est fermée. Donnez au chemin WebSocket une règle séparée avec Autoriser les connexions WebSocket activé et un délai adapté, ou envoyez un petit message de battement (heartbeat) plus souvent que la limite. Le guide de la connexion à l'origine présente les deux réglages.

Comment le mettre en place

Guides pas à pas dans le centre d'aide :

FAQ 504 Gateway Timeout

Un 504 vient-il de mon serveur ou du CDN ?

Dans la plupart des cas, le temps est passé sur votre origine et la périphérie est celle qui a attendu. Comparez une requête via le CDN avec une requête directe vers l'origine. Si l'origine seule est tout aussi lente, la correction se fait sur l'origine ; si elle est rapide en direct et lente seulement via le CDN, cherchez une différence de pare-feu ou de routage qui touche la connexion de la périphérie.

Quel est le délai d'origine par défaut sur cdn.com.tr ?

60 secondes sans données de votre origine. Vous pouvez le régler par règle de diffusion de 1 à 3 600 secondes dans Délai de réponse de l'origine (secondes). Sur le domaine d'une application Managed Container, le délai par défaut est de 300 secondes.

Dois-je mettre le délai à 3 600 secondes partout ?

Non. Un délai long sur tous les chemins signifie que, lorsque quelque chose casse vraiment, les visiteurs regardent un indicateur de chargement pendant une heure au lieu de recevoir une réponse en une minute, et que les requêtes bloquées s'accumulent sur votre origine. Gardez le délai par défaut pour le site et n'allongez que la règle du chemin lent par conception.

Pourquoi mon export fonctionne-t-il pour les petits fichiers et échoue-t-il pour les gros ?

Parce qu'il construit tout le fichier avant d'envoyer le premier octet. Les petits exports se terminent dans la limite, les gros non. Diffusez le fichier en flux pendant sa génération, ou lancez l'export en tâche d'arrière-plan et envoyez un lien de téléchargement une fois prêt.

Puis-je obtenir un 504 alors que mon application est rapide ?

Oui, quand les requêtes s'empilent avant de démarrer. Si tous les workers sont occupés, une requête rapide peut quand même attendre assez longtemps pour expirer. Des 504 qui n'apparaissent qu'aux heures chargées pointent vers la capacité, pas vers le code.

Rafraîchir la page aide-t-il ?

Parfois, mais chaque rafraîchissement relance le même travail lent sur votre origine. Sur les pages lourdes, des rafraîchissements répétés ajoutent de la charge au moment précis où le serveur peine déjà.