504 Gateway Timeout とは？原因と対処法

504 Gateway Timeoutは、CDN、ロードバランサー、リバースプロキシなどのゲートウェイが、接続先の上流サーバーから時間内に応答を受け取れなかったことを示します。画面にnginxやCloudFrontの名前が出ても、その製品自体が故障したとは限りません。

A 504 identifies a timeout observed by an intermediary. The root cause is commonly farther upstream: a slow application, a blocked dependency, or an overloaded database.

TL;DR

• 504は、ゲートウェイが上流の応答を制限時間内に受け取れなかった状態
• 502は上流から不正な応答、504は上流の応答待ちが時間切れ
• タイムアウト値を伸ばす前に、遅いSQL、外部API、同期処理、リソース枯渇を特定する
• 長時間処理は202 Acceptedとポーリング、ジョブキューなどで非同期化する

1. 504の意味と502・503との違い

要求は複数の中継点を通ります。応答を待っていた中継点が制限時間を使い切ると、そこで504が生成されます。したがって、504を返した機器と遅延を起こした機器は別であることが多い点が重要です。

2. 訪問者側でできる対処

1. 数十秒から数分待ち、サービスの障害情報を確認する
2. 閲覧ページであれば、一度だけ再読み込みする
3. 別の回線やブラウザでも同じか確認し、URLと発生時刻を運営者へ伝える

ただし、決済、注文、予約、口座振替、データ登録フォームはすぐに再送信しないでください。ブラウザには504が返っていても、上流では処理が完了している可能性があります。注文履歴、確認メール、管理画面を先に確認し、重複がないと分かってから再実行します。

A timeout does not prove that the operation failed. For non-idempotent requests such as payments or orders, verify the transaction state before retrying.

3. タイムアウトの連鎖を確認する

代表的な経路は「クライアント → CDN → ロードバランサー → リバースプロキシ → アプリサーバー → DB」です。既定値は製品・バージョン・構成で変更されるため、次の値は調査の出発点として扱い、実環境の設定で確認してください。

たとえばCloudFrontが30秒、ALBが60秒なら、35秒かかる処理はCloudFrontで先に打ち切られます。ALBやアプリのログに成功が残っていても、利用者には504が見えることがあります。request ID、trace ID、発生時刻を全層で揃えて追跡してください。

4. 運営者側の典型原因

遅いSQLとN+1クエリ

インデックス不足、巨大テーブルの全走査、ロック待ち、N+1クエリは定番です。アプリの総処理時間だけでなく、SQLごとの回数と時間を記録します。実行計画を確認し、不要な列や行を減らし、適切なインデックスや一括取得を検討します。

外部APIの応答待ち

決済、認証、配送など外部APIへの依存が遅いと、workerを占有したままタイムアウトします。接続timeoutと読み取りtimeoutを分け、呼び出し先ごとに短い上限、サーキットブレーカー、条件付きリトライを設定します。

重い同期処理

CSV生成、画像変換、大量メール送信、集計処理をHTTP要求内で完了させようとすると、正常系でも時間切れになりやすくなります。要求受付と処理完了を分離し、ジョブキューへ移します。

コネクションプールやworkerの枯渇

DB接続プール、HTTP接続プール、スレッド、プロセス、メモリが枯渇すると、処理そのものより待ち行列が長くなります。CPU使用率が低くても安全とは限りません。active、idle、pending、queue timeを同時に監視します。

5. 対処の優先順位

1. 発生点を特定: どの層が504を返したか、どこまで要求が届いたかをログとtraceで確認
2. 遅い区間を計測: キュー待ち、アプリ処理、SQL、外部APIを個別に計測
3. 原因を改善: クエリ最適化、キャッシュ、並列化、プール調整、容量追加を実施
4. 長時間処理を非同期化: 202 AcceptedとジョブIDを返し、ポーリングやWebhookで完了を通知
5. 最後に設定を調整: SLOと実測値を根拠に、必要な層だけタイムアウトを変更

HTTP/1.1 202 Accepted
Content-Type: application/json
Location: /api/jobs/job_123

{"jobId":"job_123","status":"queued"}

非同期APIでは、同じ要求が届いても重複ジョブを作らないようidempotency keyを利用します。状態確認APIはqueued、running、succeeded、failedなど明確な状態を返します。

6. nginxの設定例と整合ルール

nginxでは接続確立、上流への送信、上流からの読み取りを別々に設定できます。次は例であり、値をそのままコピーせず、実測値とSLOに合わせて調整してください。

upstream app_backend {
    server 127.0.0.1:8000;
    keepalive 32;
}

server {
    listen 80;

    location /api/ {
        proxy_pass http://app_backend;
        proxy_connect_timeout 3s;
        proxy_send_timeout 15s;
        proxy_read_timeout 45s;
        send_timeout 50s;

        proxy_set_header Host $host;
        proxy_set_header X-Request-ID $request_id;
    }
}

proxy_read_timeoutは応答全体の最大時間ではなく、上流から次のデータを読み取るまでの待機時間として働きます。ストリーミング応答では意味が変わるため、単純な処理時間の上限と混同しないでください。

下流ほど短くする整合ルール

DBや依存サービスを下流と呼ぶ場合は「下流ほど短く」が原則です。DBや外部APIの期限を短くし、その呼び出し元のアプリ、nginx、ALB、CDNへ向かうほど少し長い期限を設定します。これによりアプリがエラーを整形し、接続を解放する時間を残せます。

ただしCloudFrontの既定30秒など外側に短い上限がある構成では、内側を長くしても成功応答にはなりません。変更できる上限、再試行、ストリーミングの有無を含めて経路全体で設計します。

7. AWS ALB・CloudFrontでの調査

AWS ALB

ALBアクセスログで504の時刻、target、target_processing_timeを確認し、同じ時刻のターゲット側ログと突き合わせます。idle timeout超過だけでなく、ターゲットへの接続確立やSSLハンドシェイクの問題も候補です。ヘルスチェック成功だけで、実リクエストの依存先まで正常とは判断できません。

CloudFront

該当BehaviorとOriginの関連、origin read timeout、接続試行回数を確認します。配信ログからエッジ側の結果を確認し、ALBやオリジンログへ時刻とrequest IDをつなぎます。キャッシュミス時だけ504になるなら、オリジン経路が有力です。

8. アンチパターン

全層のタイムアウトを一律に伸ばす

原因を特定せず30秒を300秒へ伸ばすと、遅い要求がworker、接続、メモリを長時間保持します。少数の遅延が全体の枯渇へ広がります。延長が必要でも、p95・p99、SLO、同時実行数を根拠に対象を限定します。

無条件リトライで重い処理を多重実行する

CDN、SDK、アプリがそれぞれリトライすると、1要求が多数の上流処理へ増幅されます。POSTの重複実行は二重課金や二重登録にもつながります。冪等な操作へ限定し、指数バックオフ、jitter、回数上限、idempotency keyを組み合わせます。

平均値だけを見る

平均が1秒でも、一部の要求が60秒を超えれば504は発生します。エンドポイント、テナント、SQL、外部APIごとにp95・p99と最大値を確認し、遅い少数を切り分けます。

9. よくある質問 / FAQ

504と502の違いは？

502はゲートウェイが上流から無効な応答を受け取った状態、504は時間内に応答を受け取れなかった状態です。どちらも中継点から見た結果なので、上流のログ確認が必要です。

504はリロードしてもいい？

閲覧なら時間を置いて一度だけ試せます。決済、注文、予約、フォーム送信では、処理済みなのに応答だけ失われた可能性があります。履歴や確認メールを先に確認し、二重送信を避けてください。

タイムアウト値はどう決めるべき？

正常時のp95・p99、サービスのSLO、同時実行数、呼び出し元がエラー処理に必要な余裕から決めます。まず遅い処理を改善し、依存先から利用者側へ段階的に長くなるよう整合させます。

10. English summary

504 Gateway Timeout means that a gateway or proxy did not receive a response from its upstream server before a timeout expired. Unlike a 502, which indicates an invalid upstream response, a 504 indicates that the response was too late. Trace one request across CloudFront, an AWS ALB, nginx, the application, external APIs, and the database. Correlate logs with a request ID and compare actual latency with every timeout in the chain.

Fix slow SQL, N+1 queries, blocked dependencies, synchronous batch work, and exhausted pools before increasing timeout values. Move legitimate long-running work to a job queue and return 202 Accepted with a status endpoint. Retry only safe or idempotent operations, using bounded exponential backoff and an idempotency key where appropriate.

よくある質問 / FAQ

504と502の違いは？

502 Bad Gatewayはゲートウェイが上流から無効な応答を受け取った状態、504 Gateway Timeoutは上流の応答を制限時間内に受け取れなかった状態です。

504はリロードしてもいい？

閲覧だけなら時間を置いて再読み込みできます。ただし決済、注文、予約、送信フォームでは処理だけ完了している可能性があるため、履歴を確認せず再送信すると二重処理になる危険があります。

nginxで504が出た時に確認する設定は？

まずerror.logと上流アプリの処理時間を確認し、その後proxy_connect_timeout、proxy_send_timeout、proxy_read_timeoutを確認します。値の延長より先に遅い処理を特定してください。

AWS ALBの504の定番原因は？

ターゲットがALBのidle timeout内に応答しない、ターゲットへの接続が確立できない、SSL接続に失敗する、または上流の処理が詰まっているケースが代表的です。ALBアクセスログとターゲット側ログを同じ時刻・request IDで突き合わせます。

What does 504 Gateway Timeout mean?

It means a gateway or proxy did not receive a timely response from an upstream server. Trace the request across the CDN, load balancer, reverse proxy, application, and database to find the layer that exhausted its timeout.

タイムアウト値はどう決めるべき？

正常時のp95・p99レイテンシ、SLO、再試行回数、各層の役割を基準に決めます。呼び出し元が異常を処理できる時間を残すため、一般に上流サービス側を短く、利用者に近い側を少し長くします。

関連ツール / Related tools

• HTTP Status Codes

関連ガイド / Related guides

• 502 Bad Gatewayの原因と対処
• 503 Service Unavailableの原因と対処
• 502・503・504の違い
• ECONNREFUSEDとETIMEDOUTの違い