ステータスコードの分類と意味
ステータスコードは 3 桁の数字であり、先頭の数字によって次の 5 つに分類されます。
| ステータスコード | 意味 | 説明 |
|---|---|---|
| 1xx | 処理中 | クライアントはそのままリクエストを継続するか、サーバの指示に従ってプロトコルをアップデートして再送信する必要があり |
| 2xx | 成功 | |
| 3xx | リダイレクト | クライアントはこのステータスコードを受け取ったとき、レスポンスメッセージの Location ヘッダを見て新しいリソースへ接続する必要があり |
| 4xx | クライアントエラー | エラーを解消しない限り、同じリクエストをそのまま再送信することはできません。 |
| 5xx | サーバエラー | サーバ側の原因が解決すれば、同じリクエストを再送信して正常な結果が得られる可能性があります。 |
よく使われるステータスコード 9個
| ステータスコード | 意味 | ボディ | 関連メソッド | 補足：ヘッダーなど |
|---|---|---|---|---|
| 200 OK | リクエスト成功 | GETの場合はリソースの表現、その他のメソッドなら、処理結果 | すべて | |
| 201 Created | リソースの作成成功 | 新規作成されたリソースの表現、処理結果の説明 | POST PUT | レスポンスヘッダ：Location |
| 301 Moved Permanently | リソースの恒久的な移動 | 移動先のURIへのリンクを含んだHTMLなど | すべて | レスポンスヘッダ：Location |
| 303 See Other | 別のURIの参照 | 移動先のURIへのリンクを含んだHTMLなど | POST | レスポンスヘッダ：Location |
| 400 Bad Request | リクエストの間違い | エラー理由を説明する文書 | すべて | 未知の４xx系が返ってきた場合、400と同じ扱い |
| 401 Unauthorized | アクセス権不正 | エラー理由を説明する文書 | すべて | リクエストヘッダ：Authorization; レスポンスヘッダ：WWW-Authenticate |
| 404 Not Found | リソースの不在 | エラー理由を説明する文書 | すべて | |
| 500 Interal Server Error | サーバ内部エラー | エラー理由を説明する文書 | すべて | 未知の5xx系が返ってきた場合、500と同じ扱い |
| 503 Service Unavailable | サービス停止 | エラー理由を説明する文書 | すべて | レスポンスヘッダ：Retry-After |
ステータスコードとエラー処理
通常のWebサービスでは、404 Not Foundなどの場合、ボディには「ご指定のページは見つかりませんでした」というメッセージを含める
Web APIでは、クライアントがHTMLを解釈できない可能性があるため、HTMLでではなく、解釈可能な形式でエラーメッセージを返す必要があります。
プロトコルに従ったフォーマットでエラーを返し
AtomPubクライアントはAtom形式なら、解釈できる。
Accept
クライアントがAcceptヘッダーを送信している場合は、それに応じた形式でエラーメッセージを動的に変更できます。
たとえば、
Accept:application/xhtml+xml;q=0.9,text/plain;q=0.3
と指定された場合はHTML形式で、
Accept:application/atom+xml;q=0.9,text/plain;q=0.5
と指定された場合はAtom形式で返す
ステータスコードの誤用
WebサービスでもWeb APIでも、HTTPステータスコードを正しく使用することは最低限のマナーです。しかし、一部のWebサービスやWeb APIでは、エラーを200 OKで返すことがあります。これは誤用であり、適切なエラーコードを使用する必要があります。
例えば、エラーが発生した場合に200 OKとこのWeb API固有のXML形式で返すAPIがある場合、通常のブラウザなどが200 OKと判断し、正常に処理されたと判断する可能性があるため、注意が必要です。
リクエスト
GET /test HTTP/1.1
Host:api.example.jp
レスポンス
HTTP/1.1 200 OK
Content-Type:application/xml
<error>
<code>1001</code>
<message>file not found</message>
</error>
ステータスコードを意識して設計する
WebサービスやWebAPIを開発している場合、エラーが発生した場合に返すステータスコードは非常に重要な設計上の考慮事項です。重要なことは、正しいステータスコードの使用です
ステータスコードの具体的な実装方法
| 方法名 | 場合 | 方法 |
|---|---|---|
| Apache | 静的なファイルを配信 | 配信するファイルの条件によって自動でステータスコードが決定 |
| サプレット | WebサービスやWebAPIを実装 | HttpServletResponseクラスのsetStatus()メソッドやsetError()メソッドを使ってステータスコードを数値で設定してから、数値をハードコーディングするとソースコードがわかりにくくなるので、 各ステータスコードは、HttpServletResponseの定数フィールドとしてSC_OK(200)やSC_NOT_FOUND(404)のように定義されていて、これらを使う方がよい |
| Ruby on Rails | WebサービスやWeb APIを実装する場合 | コントローラでrenderメソッドを使って結果をレンダリングする際に、引数としてステータスコードの数値を渡す |