APIを呼び出すと502が返ってきた。フロントエンドのコードは正しく見えるし、再送しても失敗する。あらゆるものを疑い始めてしまう。しかし、このステータスコードは読み方を知っていれば、問題の所在をかなり明確に教えてくれている。
HTTPステータスコードとは
ブラウザやアプリがサーバーにリクエストを送るたびに、サーバーはレスポンスとともに3桁のステータスコードを返す。コードは結果を示す。成功なのか、リダイレクトなのか、クライアントのエラーなのか、サーバーのエラーなのか。レスポンス本文の代わりになるものではないが、問題が起きたときに最初に確認すべき情報だ。
これらのコードはRFC 9110で標準化されており、それぞれに固定の意味がある。そのため、ブラウザ、プロキシ、HTTPライブラリなど、どのツールも同じ意味で解釈できる。
5つのクラスと責任の所在
先頭の数字がクラスを示す。
| クラス | 意味 | 主な責任の所在 |
|---|---|---|
| 1xx | 情報提供、処理中 | 日常の開発ではほとんど見ない |
| 2xx | 成功 | エラーなし |
| 3xx | リダイレクト | URL設定を確認する必要がある |
| 4xx | クライアントエラー | 送ったリクエストが不正、または権限がない |
| 5xx | サーバーエラー | サーバー、ゲートウェイ、またはその先のサービスに問題がある |
最も単純なルールは次のとおり。4xxは通常、呼び出し側がリクエストを直す必要があることを意味し、5xxは通常、受け手側が自分のシステムを確認する必要があることを意味する。
日常でよく見るコード
200(OK)はリクエストが成功し、レスポンスに内容があることを示す。201(Created)は新しいリソースが作成されたことを示し、APIでデータを追加したときによく見られる。
301と302はブラウザを別のURLへ移動させる。301は恒久的、302は一時的なリダイレクトだ。サイトのURL構造を変えた後、誤ったリダイレクトが問題を起こすことはよくある。
400(Bad Request)はサーバーがリクエストを理解できなかったことを示す。多くの場合、JSONの形式が不正か、パラメータが欠けている。401(Unauthorized)は認証が不足していることを示す。ログインしていない、またはトークンが期限切れといった状態だ。403(Forbidden)は認証はされているが権限がないことを示す。401と403の混同は非常によくあるので、違いを覚えておく価値がある。
404(Not Found)はそのアドレスにリソースが存在しないことを示す。APIの場合は通常、レコードが見つからなかったことを意味するが、必ずしもそうとは限らない。
500(Internal Server Error)は、サーバーが予期しない障害に遭遇したことを示す。多くは未処理の例外が原因だ。502(Bad Gateway)は、ゲートウェイまたはプロキシが、その背後のサーバーから不正なレスポンスを受け取ったことを示す。503(Service Unavailable)は、サーバーが一時的にリクエストを処理できないことを示し、過負荷やメンテナンスが原因であることが多い。504(Gateway Timeout)は、ゲートウェイが上流のサーバーの応答を待ちすぎて、何も返ってこなかったことを示す。
ステータスコードで問題の範囲を絞り込む
問題が起きたら、まずコードを確認する。4xxなら、リクエスト自体を確認する。URL、メソッド、ヘッダー、ボディ、トークンなどだ。5xxなら、ログと各コンポーネントの状態を見て、サーバー、ゲートウェイ、その先のサービスのどれが失敗しているかを特定する。502、503、504の場合、リクエストの経路は見た目より長いことが多いので、各区間を確認する必要がある。
注意点として、すべてのAPIが正しいコードを返すわけではない。業務エラーでも200を返し、ボディのerrorフィールドにエラーを入れるケースがある。ステータスコードは出発点であり、最終的な結論ではない。必ずレスポンス本文とログも合わせて確認しよう。
数百個のコードを暗記する必要はない。クラスを覚え、よく出る数個のコードを覚え、まずどちら側の問題かを問う。それだけでデバッグの時間は大きく減る。