HTTP 504 Gateway Timeout — 原因と対処法

HTTP 504 の意味

HTTP 504 Gateway Timeout は、プロキシ、ロードバランサー、または CDN が発行するもので、アップストリームサーバーへのリクエストがタイムアウト内に一切応答を受け取らなかったことを示します。アップストリームが不正な応答を返した 502 とは異なり、504 では時間内に一切応答がありませんでした。

根本原因は、ほぼ常に裏側にある何か遅いものです: コストの高いデータベースクエリ、応答しない外部 API、または負荷によって枯渇したアプリケーションのスレッドプールなどです。

504 エラーのよくある原因

遅いデータベースクエリや欠落したインデックスにより、1 つのエンドポイントがプロキシの許容時間より長くかかっています。
アプリケーションが、それ自体が遅い、またはダウンしている外部 API を待っています。
バックエンドが飽和状態です: すべてのワーカーがビジー状態で、リクエストがタイムアウトを超えてキューイングされています。
プロキシとアップストリームの間のネットワークの問題です（ルーティング、パケットロス、DNS）。
タイムアウトの不一致です: アプリは正当に 60 秒必要としているのに、プロキシは 30 秒で打ち切っています。

訪問者としての対処法

少し待ってから再試行してください — 単発の 504 は多くの場合、障害ではなく単に 1 つの遅いリクエストです。
送信したアクション（支払い、注文）については、再試行する前に、それが実際に処理されたかどうかを確認してください。

開発者としての対処法

アクセスログや APM で遅いエンドポイントを見つけてください: クエリを修正し、インデックスを追加し、結果をキャッシュしてください。
遅い処理はバックグラウンドジョブに移し、クライアントがポーリングできるステータスとともに素早く応答を返してください。
最も遅いリンクが把握され、意図されたものになるよう、タイムアウトの予算をエンドツーエンドで（アプリ < プロキシ < CDN の順に）揃えてください。
不安定な外部 API がワーカーを停止させてしまわないよう、サーキットブレーカーを追加してください。

レスポンス例

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

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

よくある質問

504 と 502 の違いは何ですか？

504 はアップストリームがタイムアウト内に一切応答しなかったことを意味し、502 は何か無効なもので応答したことを意味します。

504 はユーザーの接続の問題ですか？

いいえ — これはサイトのプロキシとそのバックエンドの間の問題です。ユーザーのネットワークは正常です。

504 が発生した場合、送信したリクエストは処理されましたか？

おそらくはい — タイムアウトはレスポンスに達したものであり、必ずしも処理そのものではありません。冪等でないアクションを盲目的に再試行する前に状態を確認してください。