4.2 ステータスコードを正しく使う

ステータスコードは HTTP のレスポンスヘッダの先頭に必ず入っている 3 桁の数字。リクエストがサーバによって処理された際のステータスを表す。

汎用的な HTTP のクライアントライブラリは基本的にステータスコードをみて振る舞いを決めるため、適切なステータスコードを返さないと余計な問題を引き起こすことになる。

指定したデータの取得、あるいはリクエストした処理が成功した場合には 200 番台のステータスコードを返す。

DELETE 時には基本的にはデータを返さない。PUT/PATCH, POST の場合はデータを返す。

リダイレクト等で使用される。
リダイレクトの場合はLocationというレスポンスヘッダにリダイレクト先の新しい URI が含まれる。

ウェブサイトのように URI の変更にともなってリダイレクトを行うのは好ましくない。
クライアント側でリダイレクトにたいして実装をしているかわからないため。
何らかの理由でリソースが別の URI に変わる等でリダイレクト行う可能性がある場合は、必ずドキュメントに記載を行う。

サーバー側には問題はないが、クライアントが送ってきたリクエストが理解できなかったり、実行が許可されていない場合には 400 番台のステータスコードを返す。

400 Bad Request (ほかの 400 番台ステータスコードに当てはまらない場合)
401 Authentication (認証エラー: アクセス元が識別できない)
403 Authorization (認可エラー: 操作が許可されていない)
404 Not Found (アクセスしようとしたデータが存在しない)
(指定したデータが存在しないのか、URI が存在しないのか詳しい情報の返却が必要)
405 Method Not Allowed (エンドポイントは存在するがメソッドが許可されていない)
406 Not Acceptable (クライアント指定のデータ形式に API が対応していない)
408 Request Timeout (タイムアウト)
409 Conflict (リソース競合: 同じ ID でユーザー登録を使用とする等)
410 Gone (アクセスしたデータかつて存在したが、現在は存在しない場合。404 との違いはデータがかつて存在していたかどうか)
413 Request Entity Too Large (リクエストボディが大きすぎる)
414 Request-URI Too Long (リクエストヘッダが大きすぎる)
415 Unsupported Media Type (リクエストヘッダの Content-Type で指定されているデータ形式にサーバー側が対応していない場合 (リクエストボディのデータ形式))
429 Too Many Requests (アクセス回数が許容範囲の限界を超えた場合)

サーバー側に問題があった場合は 500 番台のエラーを返す。

500 番台のエラーはログを監視し、管理者に通知が行くように設定、再発防止を図る。