HTTP 502 Bad Gateway — 原因と対処法

HTTP 502 の意味

HTTP 502 Bad Gateway は、nginx、ロードバランサー、Cloudflare といった仲介者から発生します。それらはあなたのリクエストをアップストリームサーバーに転送し、接続拒否、レスポンス途中でのクラッシュ、HTTP としてパースできないバイト列といった無効なレスポンスを受け取りました。

名指しされる犯人がプロキシ自体であることはほとんどありません。実際には、その背後にあるアプリケーションサーバーがダウンしている、過負荷になっている、または到達不能になっていることが原因です。

502 エラーのよくある原因

アプリケーションサーバー（PHP-FPM、Node、gunicorn など）がクラッシュしたか、実行されていません。
プロキシが誤ったポート／ソケットを指しているか、ファイアウォールがアップストリームへの接続をブロックしています。
アップストリームのレスポンスがバッファを超過した、または転送途中でタイムアウトしました。
トラフィックが流れている最中にデプロイがバックエンドを再起動しました。
Cloudflare のような CDN の場合: エッジは正常なのに、オリジンサーバーがダウンしています。

訪問者としての対処法

1 分ほど待ってから再読み込みしてください — デプロイ中の 502 は自然に解決します。
それが頻発する場合は、そのサービスのステータスページを確認してください。

開発者としての対処法

アップストリームのプロセスが生きていて、プロキシが期待するアドレスでリッスンしているか確認してください。
プロキシのエラーログを読んでください — nginx は理由を正確に示します（connect() failed、upstream prematurely closed など）。
プロキシとアプリの間のポート、Unix ソケットのパス、ファイアウォールルールを確認してください。
ロードバランサーが機能していないインスタンスへのルーティングを停止するよう、ヘルスチェックを追加してください。

レスポンス例

HTTP/1.1 502 Bad Gateway
Server: nginx
Content-Type: text/html

<html><body><h1>502 Bad Gateway</h1></body></html>

よくある質問

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

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

なぜ Cloudflare は 502 を表示するのですか？

Cloudflare のエッジが、あなたのオリジンサーバーから有効なレスポンスを取得できませんでした — オリジンがダウンしている、到達不能である、または不正な形式のレスポンスを返しています。

502 は一時的なものですか？

通常はい — デプロイや再起動によって一時的な 502 が発生します。持続的な 502 は、バックエンドが本当にダウンしているか、設定に問題があることを意味します。