400番台は最も種類が豊富で、200番台の次によく使うであろうステータスコード。クライアントのリクエストに起因するエラー、すなわちサーバ側には問題はないが、クライアントのリクエストが理解できないであったり、理解はできるが実行が許可されていない場合に利用するステータスコード。
もちろんAPIの種類や性格によってエラーは千差万別であり、400番台だけでは表せない。ステータスコードはクライアントがたとえエラーの詳細を得るための仕様を知らなくても、おおよその問題を把握できるようにするためのものと捉える。
400 Bad Request
そのほか。つまり他の400番台では表すことができないエラーに使うためのステータスコード。
パラメータに間違いがある場合など、他のステータスコードで適切なものがない場合に400を返す。
401 Unauthorized / 403 Forbidden
よく似ている2つなので、間違いやすいですが、
- 401 認証のエラー
- 「あなたが誰であるのか分からないよ」
- 403 認可のエラー
- 「あなたが誰であるか分かったけど、この操作はあなたには許可されていないよ」
を表す。
404 Not Found
「アクセスしようとしたデータは存在していないよ」という意味のエラー。存在しないユーザーの情報を取得しようとしたり、そもそも存在しないエンドポイントにアクセスしようとした場合に404が返る。
一方で「何が存在しないのか」というのはケースバイケースであり、単に404を返すだけではクライアントにとってエラーハンドリングが難しくなる。
たとえば、利用者がユーザー情報を取得しようとして404が返ってきた場合、
- そのユーザーが存在しない
- エンドポイントのURIがそもそも間違っている
といった理由が考えられますが、404だけでは分かりません。利用者の開発効率を上げるためにも、詳しい情報をつけて返すと親切。
405 Method Not Allowed
エンドポイントは存在するが、メソッドが許可されていない場合に利用する。
- GETを使ってアクセス可能な検索専用のAPIにPOSTでアクセスしようとした場合
- 情報を更新する専用のAPIにGETでアクセスしてしまった場合
などに405を返す。
406 Not Acceptable
クライアントが指定してきたデータ形式にAPIが対応していない場合に返すエラー。たとえば出力形式としてJSONやXMLしか対応していないのにYAMLを指定された、といった場合に406を返す。
408 Request Timeout
リクエストをクライアントがサーバを送るのに時間がかかりすぎてサーバ側でタイムアウトを起こした際に発生する。
409 Conflict
リソース競合が発生した場合のエラー。
たとえばIDなどユニークキーを指定して新しいデータを登録するようなAPIがあったとして、既に同じIDのデータが存在する時などに409のエラーを返す。
410 Gone
404と同じくアクセスしたリソースが存在しないことを表し、単に存在しないというではなく、かつて存在したけれど今はもう存在しないことを表す。
このステータスコードを返すためには、データを削除したという情報を保持する必要があり、それを保持していることを利用者からも分かってしまうので、ユーザー情報をメールアドレスで検索するといったAPIで410を返すという仕様は個人情報保護などの観点から問題を指摘される可能性がある。