3.6 エラーの表現
3.6 エラーの表現
クライアント側がエラーの原因の調査・特定に役立つ情報をなるべく多く返す必要がある。
3.6.1 ステータスコードでエラーを表現する
| ステータスコード | 意味 |
|---|---|
| 100 番台 | 情報 |
| 200 番台 | 成功 |
| 300 番台 | リダイレクト |
| 400 番台 | クライアントサイドに起因するエラー |
| 500 番台 | サーバーサイドに起因するエラー |
データとしてエラー情報を返すが、HTTP レスポンスのステータスコードとして 200 番台を返すようなことはしてはならない。
適切なステータスコードで返すことで、クライアント側の原因特定につながる。
ピッタリくるステータスコードが存在しない場合は、"200", "400" 等の 00 番を利用する。
3.6.2 エラーの詳細をクライアントに返す
ステータスコードは汎用的な意味を表す。→エラーの詳細情報も返す必要がある。
エラーの内容を返す方法は大きく 2 つ。
- レスポンスヘッダに入れる
("X-MYNAME-ERROR-MESSAGE: Bad authentication token" のように独自のヘッダ項目を利用する) - レスポンスボディに入れる
ほとんどの API はレスポンスボディにエラー情報を入れて返している。
→クライアント側の利便性がよいためか
3.6.3 エラー詳細情報には何を入れるべきか
返す内容は以下の通り。
- エラーの詳細コード
- エラーメッセージ (人間が読める形式)
- さらなる情報が記載されたドキュメントページの URI
エラーの詳細情報は API ごとに決める。既存のステータスコードと区別できるようにする。4 桁数字でステータスコードと同様に番台でカテゴリ分けするとよい。
エラーメッセージエンドユーザーに直接表示できるような「非開発者向けメッセージ」と開発者が原因特定に利用できるような「開発者向けメッセージ」を両方含める方法もある。
3.6.4 エラーの際に HTML が返ることを防ぐ
基本的に API の結果は JSON や XML で返ることを期待される。
nginx 等のサーバーやアプリケーションフレームワークでデフォルトで 404 エラー等が HTML で返ることになっていることが多い。
エラー発生時でも適切なフォーマットでデータが返るようにする。
3.6.5 メンテナンスとステータスコード
API を停止しなければならない自体は極力避けるべき。API を利用しているサービスが動作しない、または一部動作が制限されるため。
メンテナンスで停止する場合は 503（HTTP 503 Service Unavailable）を返す。
予定されたメンテナンスで終了予定時刻が分かっている場合はそれも通知するべき。
Retry-Afterという HTTP ヘッダにいつメンテナンスが終わるかを具体的な日付や、現在時刻からアクセス可能になるまでの秒数を入れる。
3.6.6 意図的に不正確な情報を返したい場合
セキュリティ上やその他の理由で情報を曖昧にしたいケースが存在する。
ブロック機能がある場合に、ブロックされたユーザーがブロックしたユーザー情報を取得しようとした場合等。エラーで返すが、メッセージでブロックされていると伝えるとさらなるトラブルにつながる可能性がある。
→「ブロックされた側からみるとブロックした側はすでに存在しないと同義」として 404 を返すことも可能。
ログイン時に「メールアドレスが存在しない」「パスワードが違う」等の原因を伝えるのは悪意を持ったユーザーに対しても情報を与えることになる。
正確な情報を返すのはあくまでも開発の効率化やユーザー体験の向上のため。
正確な情報を返すことでそれらが阻害されるならば返すべきではない。