APIが返す404と500の違い、説明できる？現場で役立つHTTPステータスコード完全ガイド
#development
導入：「APIが動かないんだけど」だけじゃわからない
「博士！ フロントエンドの先輩から『API動かないんだけど』って言われたんだけど、何を調べればいいかわからないぜ！」
「まずはHTTPステータスコードを確認するのじゃ。ブラウザのDevToolsのNetworkタブを開いて、レスポンスのStatusを見てみなさい。」
「ステータスコードがわかれば『サーバーの問題なのか』『リクエストの問題なのか』『認証の問題なのか』が一発で切り分けられるわよ。」
「404は知ってるぜ！ ページが見つからないってやつだろ？」
「それだけじゃ全然足りないわよ…。」
1. 知らないと恥ずかしい？現場で頻出するステータスコード
「ステータスコードは大きく5つの区分に分かれておる。特に開発現場で遭遇しやすいものを重点的に解説しよう。」
| 番号帯 | 意味 | 一言で言うと |
|---|---|---|
| 1xx | 情報応答 | 「処理中だよ」 |
| 2xx | 成功 | 「うまくいったよ」 |
| 3xx | リダイレクト | 「別の場所を見てね」 |
| 4xx | クライアントエラー | 「あなたのリクエストがおかしい」 |
| 5xx | サーバーエラー | 「サーバー側で問題発生」 |
現場で特に重要なステータスコード
- 200 OK：正常にレスポンスを返せた
- 201 Created：リソースの新規作成に成功（POST成功時に使う）
- 301 / 308：恒久的なリダイレクト（SEOで重要）
- 400 Bad Request：リクエストの形式が不正（バリデーションエラー）
- 401 Unauthorized：認証されていない（トークン切れなど）
- 403 Forbidden：認証済みだが権限がない
- 404 Not Found：リソースが見つからない
- 429 Too Many Requests：レート制限に引っかかった
- 500 Internal Server Error：サーバー側の未処理エラー
- 502 Bad Gateway：バックエンドサーバーの応答異常
- 503 Service Unavailable：メンテナンス中やサーバー過負荷
2. ステータスコードで「障害の原因」を即座に切り分ける
「ステータスコードは、障害対応における最初のトリアージ（振り分け）に使えるのじゃ。」
401 vs 403：認証と認可の違い
「401と403って何が違うんだ？ どっちもアクセスできないんだろ？」
「全然違うわよ。401は『そもそもログインしてない（または期限切れ）』で、403は『ログインしてるけど権限がない』の。対処法が全く異なるから、ここを混同すると障害対応が迷走するわ。」
502 vs 503 vs 504：サーバーダウンの切り分け
502はロードバランサーがバックエンドから不正な応答を受けたとき、503はサーバーが過負荷やメンテナンス中のとき、504はバックエンドからの応答がタイムアウトしたときに返されます。 この違いを理解していれば、「Nginxの設定問題なのか」「アプリサーバーの問題なのか」「DBの応答遅延なのか」を即座に判断できます。
当サイトのHTTPステータスコード検索ツールを使えば、 コード番号を入力するだけで詳細な説明と適切な対処法を確認できます。
3. プロが教える「一歩先の」テクニカルTips
「ステータスコードの正しい使い分けは、API設計の品質を左右するのじゃ。」
Tips 1: APIレスポンスのステータスコードを正しく設計する
「全部200で返して、ボディ内のerrorフラグで判定する」設計はアンチパターンです。 HTTPステータスコードを正しく使い分けることで、フロントエンド側のエラーハンドリングがシンプルになり、 モニタリングツールでのエラー検知も正確になります。
Tips 2: リダイレクトの301と302を使い分ける
301（恒久的リダイレクト）はSEOの評価を引き継ぎます。ドメイン移行やURL構造の変更に使います。302（一時リダイレクト）はメンテナンスページへの一時誘導やA/Bテストに使います。 間違えるとSEO評価が損なわれるため、選択には注意が必要です。
🚨 現場の注意点：429（レート制限）を無視しない
外部APIを利用するとき、429が返ってきたら必ず Retry-After ヘッダーを確認してから再試行してください。 無限リトライはAPI側からIPブロックされる原因になります。 Exponential Backoff（指数バックオフ）を実装するのが安全です。
「HTTPステータスコードは、Web開発者にとっての共通言語じゃ。 この言語を正しく理解すれば、障害対応のスピードも、API設計の品質も格段に上がるぞ。 困ったときはHTTPステータスコード検索ツールですぐに確認するのじゃ！」