APIを設計していて、APIのエラー情報には何を含めるべきか悩んでいたところ、 エラー情報の標準的な形式は、RFC 7807 - Problem Details for HTTP APIsで定められていることを知った
このRFC7807について整理する
RFC7807について
エラー応答形式を定義したもの
標準化段階はPS(Proposed Standard:標準化へ提唱中)
解決したい問題点
前書きでは以下のように書かれている
たとえば、クライアントのアカウントに十分なクレジットがないことを示す応答を考えた場合、一般的に403 Forbiddenステータスコードをソフトウェア(クライアントライブラリ、キャッシュ、プロキシなど)に通知するが、それでは、リクエストが禁止された理由、該当するアカウントの残高、または問題の修正方法に関する十分な情報がAPIクライアントに提供されない。
つまり、これまでの一般的なステータスコードとメッセージだけでは、エラーに関する十分な情報がAPIクライアントに提供されないことを問題点としている
また、それを解決しようとして、新しいエラーレスポンス書式を各所で定義しようとしてしまうことも問題だとしている
これを回避するために、HTTPレスポンスにおける読解可能なエラーの詳細を伝達するための “問題詳細” というものを定義する
問題詳細
問題詳細には以下の情報を含める様に定義している
"type"(文字列): 問題タイプを識別するURI (RFC3986)
この仕様は、 問題タイプについて人間が読めるドキュメント(例えばhtml)を提供することを推奨
存在しない場合は、値は「about:blank」とみなされる"title"(文字列): 人間が読める形式の短い問題
タイプの要約
ローカライズの目的を除いて、問題の発生の度に変更すべきではない"status"(数値): この問題の発生に対してオリジンサーバーによって生成されたHTTPステータスコード
- "detail"(文字列): この問題の発生に対する人間が読める説明
- "instance"(文字列): 特定の問題の発生を識別するURI参照
参照先のデータを取得した際には、更なる情報を得られる可能性がある
ほかのサービスはどうしているか
良記事をみつけた
qiita.com
サービスによって様々なのがわかった
確かに「type」より「code」とか「errorCode」とかをよく見かける気がする
参考
RFC 7807 - Problem Details for HTTP APIs
HTTP APIの詳細なエラー情報をレスポンスに持たせるための仕様