それぞれのステータスコードの意味はMDN等でよくまとめられていますが、逆に「どんなエラーのときにどのステータスコードを返せばいいのか」という情報はあまりありません。
そこで、逆引きリファレンスとしてまとめてみました。
400系 vs 500系
まず気になるのは、返すエラーは400系なのか500系なのかということ。わかりやすい基準はクライアントのリクエストに問題がある場合は400系、サーバーサイドに問題がある場合は500系です。
具体的には「パラメーターが足りない」「パラメーターの型がおかしい」といったものは400系、「DBサーバーに接続できない」といったものは500系です。
ビジネスロジックまわりで出てくるエラーはほとんどが400系です。
パラメーター関連
チェックするであろう順番に並べています。Content-Typeがおかしい
JSON形式（application/json）のデータしか受け付けていないAPIで、URLエンコード（application/x-www-form-urlencoded）がContent-Typeとして指定された場合。415 Unsupported Media Type を返します。
必要なパラメーターがない
認証APIに、認証に必要なユーザーIDやパスワードなどのデータが渡されなかった場合。400 Bad Request を返します。
パラメーターの形式がおかしい
数値を要求しているところで"123"のような数値文字列が渡された場合、あるいは"abc"のように数値に変換できない文字列が渡された場合。400 Bad Request を返します。
数値文字列でもエラーを返すか、あるいは数値に変換して何事もなかったかのように進めるかはAPIの仕様次第です。仕様書に明記しておきましょう。
存在しないリソースにアクセスしようとした
ID=0のユーザー情報を取得しようとした場合。404 Not Found を返します。
認証情報を付加せずに、認証が必要なリソースにアクセスした
Authorizationヘッダーをつけずにユーザー情報を変更しようとした場合。401 Unauthorized を返します。
このエラーは「権限はないが、リソース自体は存在している」という情報を利用者に与えてしまうため、セキュリティ上の懸念がある場合は404を返しても構いません。
下の2つも同様です。
誤った認証情報で、認証が必要なリソースにアクセスした
Authorizationヘッダーはついているが、認証トークンがでたらめな文字列の場合。401 Auauthorized を返します。
権限を持たない認証情報で、認証が必要なリソースにアクセスした
認証トークン自体は正しいが、別のユーザーの情報を参照しようとした場合。403 Forbidden を返します。
DBの制約違反に相当する操作を行おうとした
すでに登録されているユーザー名で別のユーザーを登録しようとした場合（一意性違反）や、購入履歴のある商品を削除しようとした場合（外部キー制約違反）。409 Conflict を返します。
処理できるが、アプリケーションの仕様上受け付けられない
生年月日を1回しか変更できないアプリケーションで2回以上変更しようとした場合。422 Unprocessable Entity を返します。
整合性が崩れるといった論理的な破綻はないものの、仕様上拒否している場合に使います。
他にも「商品一覧の取得上限が100件だけど200件取得しようとした場合」なども含まれますが、エラーを出さずに上限の100件を返しても構いません。これも仕様書に明記しておきましょう。
まとめ
多いようで少なく、少ないようで多いですね。特に間違えやすいのは、認証関係の401/403やパラメーターを受け付けるか否かの400/409/422だと思います。
ステータスコードの意味をしっかり理解しましょう。
0 件のコメント:
コメントを投稿