HTTP 504 Gateway Timeout — Causes et corrections

Ce que signifie HTTP 504

HTTP 504 Gateway Timeout est émis par un proxy, un load balancer ou un CDN dont la requête vers le serveur backend n'a reçu aucune réponse dans son délai imparti. Contrairement à 502 — où le backend a mal répondu — avec 504 il n'a pas répondu du tout à temps.

La cause racine est presque toujours quelque chose de lent en coulisses : une requête de base de données coûteuse, une API externe qui ne répond pas, ou un pool de threads applicatif affamé par la charge.

Causes courantes des erreurs 504

Une requête de base de données lente ou un index manquant faisant qu'un endpoint prend plus de temps que ce que le proxy autorise.
L'application en attente d'une API externe elle-même lente ou en panne.
Backend saturé : tous les workers occupés, requêtes en file d'attente au-delà du délai.
Problèmes réseau entre le proxy et le backend (routage, perte de paquets, DNS).
Décalage de timeout : l'application a légitimement besoin de 60s, le proxy coupe à 30s.

Comment la corriger en tant que visiteur

Réessayez après un instant — un 504 isolé est souvent une seule requête lente, pas une panne.
Pour une action que vous avez soumise (paiement, commande), vérifiez si elle est réellement passée avant de réessayer.

Comment la corriger en tant que développeur

Trouvez l'endpoint lent dans les logs d'accès/APM : corrigez la requête, ajoutez des index, mettez le résultat en cache.
Déplacez le travail lent vers des jobs en arrière-plan et renvoyez rapidement un statut que le client peut interroger.
Alignez les budgets de timeout de bout en bout (app < proxy < CDN) afin que le maillon le plus lent soit connu et intentionnel.
Ajoutez des circuit breakers autour des API externes instables plutôt que de laisser vos workers se bloquer.

Exemple de réponse

HTTP/1.1 504 Gateway Timeout
Server: nginx
Content-Type: text/html

<html><body><h1>504 Gateway Timeout</h1></body></html>

FAQ

Quelle est la différence entre 504 et 502 ?

504 signifie que le backend n'a jamais répondu dans le délai imparti ; 502 signifie qu'il a répondu par quelque chose d'invalide.

Un 504 est-il un problème de connexion de l'utilisateur ?

Non — c'est entre le proxy du site et son backend. Le réseau de l'utilisateur va bien.

Ma requête soumise a-t-elle été traitée si j'ai reçu un 504 ?

Peut-être — le timeout a touché la réponse, pas nécessairement le traitement. Vérifiez l'état avant de réessayer aveuglément des actions non idempotentes.