APIのHTTPステータスコードについて考える

APIではHTTPステータスコードが大事な意味を持ちます。それによってクライアントではエラーが起きたかどうかを判断します。ステータスコードが200でエラーオブジェクトが返ってくると言うのはとても変な状態と言えます。

そこで今回は主なステータスコードとその使い方を紹介します。

正常系

正常系は200番台で表されることが多いです。

200 OK

最も一般的なステータスコードです。単にOKという意味であったり、アップデートや削除が完了した際にも200を使います。

201 Created

新規作成の場合だけ201としているケースがあります。RESTfulであれば、POSTメソッドだけ201にしていることが多いです。

202 Accepted

あまり多くありませんがバッチ処理が受け付けられた場合に返すことがあります。

リダイレクト系

300系のリダイレクトは時々使われますが、APIのURLを変更するのは良い仕様ではないのでお勧めしません。クライアントが自動的にURLを変更してくれなかったり、OAuth2のようにシグネチャ生成の中にパス情報が入っている場合、リダイレクトは生成エラーにつながるでしょう。

301 Moved Permanently

恒久的にURLが変わった場合に使います。

302 Found

URLが一時的に変わった場合に使います。これはお勧めしません。

クライアントエラー系

システム側で正常なエラー処理として判断されるものは400番台を使います。

400 Bad Request

リクエストが不正な場合に指定します。シグネチャ生成のエラーに用いたりします。

401 Unauthorized

認証エラーの場合に使います。ID/パスワード認証はもちろん、トークンベースの場合でも利用します。

402 Payment Required

決済情報が必要であったり、課金上限を超えてしまった場合に利用します。

403 Forbidden

リソースへのアクセス権限がない場合に使います。認証はOKですが、権限が足りない場合は403を使います。

404 Not Found

リソースが存在しない場合のエラーとして用います。

405 Method Not Allowed

HTTPメソッド（GET/POST/PUT/DELETE/OPTIONS/HEADなど）が許可されていない場合のエラーとして使います。アプリケーション側で実装することもありますが、一般的にHTTPサーバ側での対応になるでしょう。

406 Not Acceptable

リクエストヘッダー情報が間違っている場合に使います。mimeが間違っている場合もありますが、シグネチャが間違っていたり、セットすべきヘッダーがない場合も406を使います。

409 Conflict

更新がバッティングしたり、ユニークなIDが重複してしまった場合などに使います。

システムエラー系

500番台は主にシステムエラーになります。アプリケーション開発者が認識していなかったエラーが発生した場合はこちらを指定します。APIとして出さない方が良いエラーです。

500 Internal Server Error

主にCGI系のスクリプトで例外エラーが発生した場合に返されます。

502 Bad Gateway

アプリケーションサーバが落ちている時にHTTPサーバが返すことが多いエラーです。

503 Service Unavailable

アプリケーションサーバ側で何らかのシステムエラーが発生した場合に返します。

他にもエラーコードは幾つかありますが、主に使うのはここで紹介したコードになるのではないでしょうか。適切なエラーコードを選ぶことで、開発者にとって分かりやすいAPIになります。開発を補助する情報として統一感をもって選ぶようにしましょう。