1. Introduction (序論)

HTTP [RFC7230] ステータスコードは、エラーに関する十分な情報を伝えるには不十分な場合があります。Web ブラウザを使用する人間は HTML [W3C.REC-html5-20141028] レスポンスボディで問題の性質を知ることができますが、いわゆる「HTTP API」の非人間的な利用者は通常そうではありません。

本仕様は、この目的に適した単純な JSON [RFC7159] および XML [W3C.REC-xml-20081126] ドキュメント形式を定義します。これらは HTTP API によって再利用されるように設計されており、HTTP API はそのニーズに固有の異なる「問題タイプ (Problem Types)」を識別できます。

したがって、API クライアントは、高レベルのエラークラス(ステータスコードを使用)と問題のより詳細な情報(これらの形式の 1 つを使用)の両方を知ることができます。

例えば、クライアントのアカウントに十分なクレジットがないことを示すレスポンスを考えてみましょう。403 Forbidden ステータスコードが最も適切と見なされる可能性があります。これは、HTTP 汎用ソフトウェア(クライアントライブラリ、キャッシュ、プロキシなど)にレスポンスの一般的なセマンティクスを通知するためです。

しかし、これでは API クライアントに、リクエストがなぜ禁止されたのか、適用可能なアカウント残高、または問題を修正する方法について十分な情報を提供しません。これらの詳細が機械可読形式でレスポンスボディに含まれている場合、クライアントは適切に処理できます。例えば、アカウントへのより多くのクレジットの転送をトリガーします。

本仕様は、特定のタイプの問題(例えば、「クレジット不足 (out of credit)」)を URI [RFC3986] で識別することによってこれを実現します。HTTP API は、自身の管理下で新しい URI を指定するか、既存の URI を再利用することでこれを行うことができます。

さらに、問題詳細には、問題の特定の発生を識別する URI(実質的に「先週の木曜日に Joe がクレジットが足りなかった時」という概念に識別子を与える)など、他の情報を含めることができ、これはサポートまたはフォレンジック目的に有用です。

問題詳細のデータモデルは JSON [RFC7159] オブジェクトです。JSON ドキュメントとしてフォーマットされる場合、application/problem+json メディアタイプを使用します。附属書 A は、application/problem+xml メディアタイプを使用する同等の XML 形式でそれらを表現する方法を定義します。

問題詳細は(当然ながら)HTTP で問題の詳細を伝える唯一の方法ではないことに注意してください。例えば、レスポンスがまだリソースの表現である場合、そのアプリケーションの形式で関連する詳細を記述することがしばしば望ましいです。同様に、多くの状況で、追加の詳細を伝える必要のない適切な HTTP ステータスコードが存在します。

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