1. Introduction (はじめに)

HTTP ステータスコード ([HTTP] のセクション 15) は, エラーに関する十分な情報を常に伝達できるとは限りません。Web ブラウザを使用する人間は HTML [HTML5] 応答コンテンツを理解できることが多いですが, HTTP API の非人間的な消費者はそれを理解することが困難です。

その欠点に対処するため, この仕様は遭遇した問題の詳細を記述するための単純な JSON [JSON] および XML [XML] ドキュメント形式を定義します -- "問題詳細" (problem details)。

例えば, クライアントのアカウントに十分なクレジットがないことを示す応答を考えてみましょう。API の設計者は, 403 Forbidden ステータスコードを使用して, 一般的な HTTP ソフトウェア (クライアントライブラリ, キャッシュ, プロキシなど) に応答の一般的なセマンティクスを通知することを決定する可能性があります。API 固有の問題詳細 (サーバーがリクエストを拒否した理由や適用可能なアカウント残高など) は応答コンテンツで伝達できるため, クライアントはそれらに対して適切に行動できます (例えば, アカウントにより多くのクレジットを転送するトリガーなど)。

この仕様は, URI [URI] を使用して特定の "問題タイプ" (problem type) (例: "out of credit") を識別します。HTTP API は, 自身の制御下にある URI を使用して自身に固有の問題を識別できます。または, 相互運用性を促進し共通のセマンティクスを活用するために既存の URI を再利用できます (セクション 4.2 を参照)。

問題詳細には, 問題の特定の発生を識別する URI など, 他の情報を含めることができます (事実上, "Joe が先週木曜日に十分なクレジットを持っていなかった時間" という概念に識別子を与えます)。これはサポートやフォレンジック目的に役立ちます。

問題詳細のデータモデルは JSON [JSON] オブジェクトです。JSON ドキュメントとしてシリアライズされる場合, "application/problem+json" メディアタイプを使用します。付録 B は同等の XML 形式を定義しており, "application/problem+xml" メディアタイプを使用します。

HTTP 応答で伝達される場合, 問題詳細の内容はプロアクティブネゴシエーションを使用してネゴシエートできます。[HTTP] のセクション 12.1 を参照してください。特に, 人間が読める文字列 (title や description など) に使用される言語は Accept-Language リクエストヘッダーフィールド ([HTTP] のセクション 12.5.4) を使用してネゴシエートできますが, そのネゴシエーションは依然として非優先のデフォルト表現が返される結果になる可能性があります。

問題詳細は任意の HTTP ステータスコードと一緒に使用できますが, 4xx および 5xx 応答のセマンティクスに最も自然に適合します。問題詳細は (当然ながら) HTTP で問題の詳細を伝達する唯一の方法ではないことに注意してください。例えば, 応答が依然としてリソースの表現である場合, そのアプリケーションの形式で関連する詳細を記述することが望ましいことがよくあります。同様に, 定義された HTTP ステータスコードは, 追加の詳細を伝達する必要のない多くの状況をカバーしています。

この仕様の目的は, 必要とするアプリケーションのために共通のエラー形式を定義することであり, それにより独自のエラー形式を定義する必要がなくなります。さらに悪いことに, 既存の HTTP ステータスコードのセマンティクスを再定義する誘惑を避けることができます。アプリケーションがエラーを伝達するためにこれを使用しないことを選択した場合でも, その設計をレビューすることは, 既存の形式でエラーを伝達する際に直面する設計上の決定を導くのに役立ちます。

[RFC7807] からの変更点のリストについては, 付録 D を参照してください。