[要約] このRFCは、HTTP APIにおいてエラー情報を詳細かつ機械可読な形式で伝えるためのJSONデータ形式「Problem Details」の最新仕様を定義しています（RFC 7807を廃止・更新）。基本的な構造を維持しつつ、レジストリの管理ルールやセキュリティ上の考慮事項を明確化し、Web APIのクライアントが一貫してエラーの原因を判別・処理できるようにするための標準的な手段を最新化しています。
Internet Engineering Task Force (IETF) M. Nottingham
Request for Comments: 9457
Obsoletes: 7807 E. Wilde
Category: Standards Track
ISSN: 2070-1721 S. Dalal
July 2023
This document defines a "problem detail" to carry machine-readable details of errors in HTTP response content to avoid the need to define new error response formats for HTTP APIs.
この文書では、HTTP APIのために新しいエラー応答形式を定義する必要性を回避するため、HTTP応答コンテンツ内でエラーの機械可読な詳細を伝達する「問題の詳細（problem detail）」を定義します。
This document obsoletes RFC 7807.
この文書は RFC 7807 を廃止します。
This is an Internet Standards Track document.
これはインターネット標準トラックの文書です。
This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on Internet Standards is available in Section 2 of RFC 7841.
この文書はインターネットエンジニアリングタスクフォース（IETF）の成果物です。これはIETFコミュニティのコンセンサスを表しています。公開レビューを受けており、インターネットエンジニアリングステアリンググループ（IESG）によって出版が承認されています。インターネット標準に関する詳細は、RFC 7841のセクション2で入手できます。
Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at https://www.rfc-editor.org/info/rfc9457.
この文書の現在の状態、正誤表（errata）、およびフィードバックの提供方法に関する情報は、https://www.rfc-editor.org/info/rfc9457 で入手できます。
Copyright (c) 2023 IETF Trust and the persons identified as the document authors. All rights reserved.
Copyright (c) 2023 IETF Trust and the persons identified as the document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.
この文書は、この文書の公開日に有効な BCP 78 および IETF 文書に関する IETF Trust の法的規定（https://trustee.ietf.org/license-info）の対象となります。これらの文書には、この文書に関するお客様の権利と制限が記載されているため、注意深く確認してください。この文書から抽出されたコードコンポーネントには、Trust の法的規定のセクション 4.e に記載されている Revised BSD License のテキストが含まれている必要があり、Revised BSD License に記載されているように無保証で提供されます。
1. Introduction
2. Requirements Language
3. The Problem Details JSON Object
3.1. Members of a Problem Details Object
3.1.1. "type"
3.1.2. "status"
3.1.3. "title"
3.1.4. "detail"
3.1.5. "instance"
3.2. Extension Members
4. Defining New Problem Types
4.1. Example
4.2. Registered Problem Types
4.2.1. about:blank
5. Security Considerations
6. IANA Considerations
7. References
7.1. Normative References
7.2. Informative References
Appendix A. JSON Schema for HTTP Problems
Appendix B. HTTP Problems and XML
Appendix C. Using Problem Details with Other Formats
Appendix D. Changes from RFC 7807
Acknowledgements
Authors' Addresses
HTTP status codes (Section 15 of [HTTP]) cannot always convey enough information about errors to be helpful. While humans using web browsers can often understand an HTML [HTML5] response content, non-human consumers of HTTP APIs have difficulty doing so.
HTTPステータスコード（[HTTP] のセクション15）は、エラーに関する十分な情報を常に伝えられるとは限らず、必ずしも有用ではありません。ウェブブラウザを使用する人間は、HTML [HTML5] のレスポンスコンテンツを理解できることが多いですが、HTTP APIの人間以外の消費者（プログラムなど）はそうすることが困難です。
To address that shortcoming, this specification defines simple JSON [JSON] and XML [XML] document formats to describe the specifics of a problem encountered -- "problem details".
その欠点に対処するために、この仕様では、発生した問題の詳細（"problem details"）を説明するための単純な JSON [JSON] および XML [XML] 文書形式を定義します。
For example, consider a response indicating that the client's account doesn't have enough credit. The API's designer might decide to use the 403 Forbidden status code to inform generic HTTP software (such as client libraries, caches, and proxies) of the response's general semantics. API-specific problem details (such as why the server refused the request and the applicable account balance) can be carried in the response content so that the client can act upon them appropriately (for example, triggering a transfer of more credit into the account).
例えば、クライアントのアカウントに十分な残高（クレジット）がないことを示すレスポンスを考えてみましょう。APIの設計者は、403 Forbidden ステータスコードを使用して、一般的なHTTPソフトウェア（クライアントライブラリ、キャッシュ、プロキシなど）にレスポンスの一般的な意味を通知することを決定するかもしれません。サーバーがリクエストを拒否した理由や該当するアカウント残高などのAPI固有の問題詳細は、レスポンスコンテンツに含めることができ、それによってクライアントは適切に対応（例えば、アカウントへのさらなるクレジットの転送をトリガーするなど）できるようになります。
This specification identifies the specific "problem type" (e.g., "out of credit") with a URI [URI]. HTTP APIs can use URIs under their control to identify problems specific to them or can reuse existing ones to facilitate interoperability and leverage common semantics (see Section 4.2).
この仕様は、特定の「問題タイプ」（例：「残高不足」）を URI [URI] で識別します。HTTP APIは、自身が管理する URI を使用して独自の問題を特定したり、既存の URI を再利用して相互運用性を促進し共通の意味を活用したりできます（セクション4.2を参照）。
Problem details can contain other information, such as a URI identifying the problem's specific occurrence (effectively giving an identifier to the concept "The time Joe didn't have enough credit last Thursday"), which can be useful for support or forensic purposes.
問題の詳細には、問題の特定の発生を識別する URI（「ジョーが先週の木曜日に十分なクレジットを持っていなかった時」という概念に実質的に識別子を与えるもの）など、他の情報を含めることができ、これはサポートやフォレンジックの目的に役立ちます。
The data model for problem details is a JSON [JSON] object; when serialized as a JSON document, it uses the "application/problem+json" media type. Appendix B defines an equivalent XML format, which uses the "application/problem+xml" media type.
問題の詳細のデータモデルは JSON [JSON] オブジェクトです。JSON 文書としてシリアル化される場合、"application/problem+json" メディアタイプを使用します。付録Bでは、"application/problem+xml" メディアタイプを使用する同等の XML 形式を定義しています。
When they are conveyed in an HTTP response, the contents of problem details can be negotiated using proactive negotiation; see Section 12.1 of [HTTP]. In particular, the language used for human-readable strings (such as those in title and description) can be negotiated using the Accept-Language request header field (Section 12.5.4 of [HTTP]), although that negotiation may still result in a non-preferred, default representation being returned.
これらが HTTP レスポンスで伝達される際、問題の詳細の内容はプロアクティブ・ネゴシエーションを使用して交渉できます（[HTTP] のセクション12.1を参照）。特に、人間が読める文字列（タイトルや説明など）に使用される言語は、Accept-Language リクエストヘッダーフィールド（[HTTP] のセクション12.5.4）を使用して交渉できますが、その交渉の結果、優先されないデフォルトの表現が返されることもあります。
Problem details can be used with any HTTP status code, but they most naturally fit the semantics of 4xx and 5xx responses. Note that problem details are (naturally) not the only way to convey the details of a problem in HTTP. If the response is still a representation of a resource, for example, it's often preferable to describe the relevant details in that application's format. Likewise, defined HTTP status codes cover many situations with no need to convey extra detail.
問題の詳細には、任意の HTTP ステータスコードを使用できますが、最も自然に適合するのは 4xx および 5xx レスポンスの意味論です。問題の詳細は（当然ながら）HTTP で問題の詳細を伝える唯一の方法ではないことに注意してください。例えば、レスポンスが依然としてリソースの表現である場合、そのアプリケーションの形式で関連する詳細を説明する方が好ましいことが多いです。同様に、定義された HTTP ステータスコードは多くの状況をカバーしており、追加の詳細を伝える必要がない場合もあります。
This specification's aim is to define common error formats for applications that need one so that they aren't required to define their own or, worse, tempted to redefine the semantics of existing HTTP status codes. Even if an application chooses not to use it to convey errors, reviewing its design can help guide the design decisions faced when conveying errors in an existing format.
この仕様の目的は、独自のエラー形式を定義する必要がなく、さらに悪いことに既存の HTTP ステータスコードの意味を再定義したくなることがないように、エラー形式を必要とするアプリケーションのために共通の形式を定義することです。アプリケーションがエラーを伝えるためにこれを使用しないことを選択した場合でも、その設計を検討することは、既存の形式でエラーを伝える際に直面する設計上の決定を導くのに役立ちます。
See Appendix D for a list of changes from [RFC7807].
[RFC7807]の変更のリストについては、付録Dを参照してください。
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
このドキュメントのキーワード "MUST"、"MUST NOT"、"REQUIRED"、"SHALL"、"SHALL NOT"、"SHOULD"、"SHOULD NOT"、"RECOMMENDED"、"NOT RECOMMENDED"、"MAY"、および "OPTIONAL" は、BCP 14 [RFC2119] [RFC8174] で説明されているように、すべて大文字で表示される場合にのみ解釈されるものとします。
The canonical model for problem details is a JSON [JSON] object. When serialized in a JSON document, that format is identified with the "application/problem+json" media type.
問題の詳細の標準的なモデルは JSON [JSON] オブジェクトです。JSON 文書としてシリアル化される場合、その形式は "application/problem+json" メディアタイプで識別されます。
For example:
例：
POST /purchase HTTP/1.1
Host: store.example.com
Content-Type: application/json
Accept: application/json, application/problem+json
{
"item": 123456,
"quantity": 2
}
HTTP/1.1 403 Forbidden
Content-Type: application/problem+json
Content-Language: en
{
"type": "https://example.com/probs/out-of-credit",
"title": "You do not have enough credit.",
"detail": "Your current balance is 30, but that costs 50.",
"instance": "/account/12345/msgs/abc",
"balance": 30,
"accounts": ["/account/12345",
"/account/67890"]
}
Here, the out-of-credit problem (identified by its type) indicates the reason for the 403 in "title", identifies the specific problem occurrence with "instance", gives occurrence-specific details in "detail", and adds two extensions: "balance" conveys the account's balance, and "accounts" lists links where the account can be topped up.
ここで、残高不足（out-of-credit）の問題（そのタイプによって識別される）は、"title" で 403 の理由を示し、"instance" で特定の問題の発生を識別し、"detail" で発生固有の詳細を提供し、さらに 2 つの拡張を追加しています。"balance" はアカウントの残高を伝え、"accounts" はアカウントを補充できるリンクをリストします。
When designed to accommodate it, problem-specific extensions can convey more than one instance of the same problem type. For example:
対応できるように設計されていれば、問題固有の拡張によって、同じ問題タイプの複数のインスタンスを伝えることができます。例：
POST /details HTTP/1.1
Host: account.example.com
Accept: application/json
{
"age": 42.3,
"profile": {
"color": "yellow"
}
}
HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json
Content-Language: en
{
"type": "https://example.net/validation-error",
"title": "Your request is not valid.",
"errors": [
{
"detail": "must be a positive integer",
"pointer": "#/age"
},
{
"detail": "must be 'green', 'red' or 'blue'",
"pointer": "#/profile/color"
}
]
}
The fictional problem type here defines the "errors" extension, an array that describes the details of each validation error. Each member is an object containing "detail" to describe the issue and "pointer" to locate the problem within the request's content using a JSON Pointer [JSON-POINTER].
ここでの架空の問題タイプは "errors" 拡張を定義しており、これは各バリデーションエラーの詳細を説明する配列です。各メンバーは、問題を説明する "detail" と、JSON Pointer [JSON-POINTER] を使用してリクエストのコンテンツ内の問題箇所を特定する "pointer" を含むオブジェクトです。
When an API encounters multiple problems that do not share the same type, it is RECOMMENDED that the most relevant or urgent problem be represented in the response. While it is possible to create generic "batch" problem types that convey multiple, disparate types, they do not map well into HTTP semantics.
APIが同じタイプを共有しない複数の問題に遭遇した場合、最も関連性が高い、あるいは緊急性の高い問題をレスポンスで表現することが推奨されます（RECOMMENDED）。複数の異なるタイプを伝える一般的な「バッチ」問題タイプを作成することも可能ですが、それらは HTTP の意味論とうまく適合しません。
Note also that the API has responded with the "application/ problem+json" type, even though the client did not list it in Accept, as is allowed by HTTP (see Section 12.5.1 of [HTTP]).
また、HTTP で許可されているように（[HTTP] のセクション12.5.1を参照）、クライアントが Accept でリストしていなかったとしても、API が "application/problem+json" タイプでレスポンスを返していることにも注意してください。
Problem detail objects can have the following members. If a member's value type does not match the specified type, the member MUST be ignored -- i.e., processing will continue as if the member had not been present.
問題の詳細オブジェクトは、以下のメンバーを持つことができます。メンバーの値の型が指定された型と一致しない場合、そのメンバーは無視されなければなりません（MUST）。つまり、そのメンバーが存在しなかったかのように処理が継続されます。
The "type" member is a JSON string containing a URI reference [URI] that identifies the problem type. Consumers MUST use the "type" URI (after resolution, if necessary) as the problem type's primary identifier.
"type" メンバーは、問題タイプを識別する URI 参照 [URI] を含む JSON 文字列です。消費者は（必要に応じて解決した後の）"type" URI を、問題タイプの主要な識別子として使用しなければなりません（MUST）。
When this member is not present, its value is assumed to be "about:blank".
このメンバーが存在しない場合、その値は "about:blank" であると想定されます。
If the type URI is a locator (e.g., those with an "http" or "https" scheme), dereferencing it SHOULD provide human-readable documentation for the problem type (e.g., using HTML [HTML5]). However, consumers SHOULD NOT automatically dereference the type URI, unless they do so when providing information to developers (e.g., when a debugging tool is in use).
タイプの URI がロケーター（例："http" や "https" スキームを持つもの）である場合、それをデレファレンス（参照解決）すると、問題タイプの人間が読めるドキュメント（例：HTML [HTML5] を使用）が提供されるべきです（SHOULD）。ただし、開発者に情報を提供する場合（例：デバッグツールの使用時）を除き、消費者はタイプの URI を自動的にデレファレンスすべきではありません（SHOULD NOT）。
When "type" contains a relative URI, it is resolved relative to the document's base URI, as per [URI], Section 5. However, using relative URIs can cause confusion, and they might not be handled correctly by all implementations.
"type" に相対 URI が含まれている場合、[URI] のセクション5に従って、ドキュメントのベース URI に対して解決されます。しかし、相対 URI を使用すると混乱を招く可能性があり、すべての実装で正しく処理されるとは限りません。
For example, if the two resources "https://api.example.org/foo/ bar/123" and "https://api.example.org/widget/456" both respond with a "type" equal to the relative URI reference "example-problem", when resolved they will identify different resources ("https://api.example.org/foo/bar/example-problem" and "https://api.example.org/widget/example-problem", respectively). As a result, it is RECOMMENDED that absolute URIs be used in "type" when possible and that when relative URIs are used, they include the full path (e.g., "/types/123").
例えば、2つのリソース "https://api.example.org/foo/bar/123" と "https://api.example.org/widget/456" が両方とも相対 URI 参照 "example-problem" に等しい "type" でレスポンスを返した場合、解決されるとそれぞれ異なるリソース（"https://api.example.org/foo/bar/example-problem" と "https://api.example.org/widget/example-problem"）を指すことになります。その結果、可能な場合は "type" に絶対 URI を使用すること、また相対 URI を使用する場合はフルパスを含めること（例："/types/123"）が推奨されます（RECOMMENDED）。
The type URI is allowed to be a non-resolvable URI. For example, the tag URI scheme [TAG] can be used to uniquely identify problem types:
タイプの URI は解決可能でない URI であっても構いません。例えば、tag URI スキーム [TAG] を使用して問題タイプを一意に識別できます。
tag:example@example.org,2021-09-17:OutOfLuck
However, resolvable type URIs are encouraged by this specification because it might become desirable to resolve the URI in the future. For example, if an API designer used the URI above and later adopted a tool that resolves type URIs to discover information about the error, taking advantage of that capability would require switching to a resolvable URI, creating a new identity for the problem type and thus introducing a breaking change.
しかし、将来的に URI を解決することが望ましくなる可能性があるため、この仕様では解決可能なタイプ URI の使用を推奨しています。例えば、API設計者が上記の URI を使用し、後にタイプ URI を解決してエラーに関する情報を発見するツールを採用した場合、その機能を利用するには解決可能な URI に切り替える必要があり、問題タイプに新しいアイデンティティを作成することになるため、破壊的な変更が生じることになります。
The "status" member is a JSON number indicating the HTTP status code ([HTTP], Section 15) generated by the origin server for this occurrence of the problem.
"status" メンバーは、この問題の発生に対してオリジンサーバーが生成した HTTP ステータスコード（[HTTP] のセクション15）を示す JSON 数値です。
The "status" member, if present, is only advisory; it conveys the HTTP status code used for the convenience of the consumer. Generators MUST use the same status code in the actual HTTP response, to assure that generic HTTP software that does not understand this format still behaves correctly. See Section 5 for further caveats regarding its use.
"status" メンバーは、存在する場合でも助言的なものに過ぎません。これは消費者の利便性のために使用された HTTP ステータスコードを伝えるものです。生成側は、この形式を理解しない一般的な HTTP ソフトウェアが正しく動作することを保証するために、実際の HTTP レスポンスで同じステータスコードを使用しなければなりません（MUST）。その使用に関するさらなる注意点については、セクション5を参照してください。
Consumers can use the status member to determine what the original status code used by the generator was when it has been changed (e.g., by an intermediary or cache) and when a message's content is persisted without HTTP information. Generic HTTP software will still use the HTTP status code.
消費者は、ステータスコードが変更された場合（例：仲介者やキャッシュによる）や、メッセージのコンテンツが HTTP 情報なしで保存されている場合に、生成側が使用した元のステータスコードを判断するために "status" メンバーを使用できます。一般的な HTTP ソフトウェアは引き続き HTTP ステータスコードを使用します。
The "title" member is a JSON string containing a short, human-readable summary of the problem type.
"title" メンバーは、問題タイプの短い人間が読める要約を含む JSON 文字列です。
It SHOULD NOT change from occurrence to occurrence of the problem, except for localization (e.g., using proactive content negotiation; see [HTTP], Section 12.1).
これは、ローカライズ（例：プロアクティブ・コンテンツネゴシエーションの使用、[HTTP] のセクション12.1を参照）を除き、問題が発生するたびに変更されるべきではありません（SHOULD NOT）。
The "title" string is advisory and is included only for users who are unaware of and cannot discover the semantics of the type URI (e.g., during offline log analysis).
"title" 文字列は助言的なものであり、タイプ URI の意味を知らない、あるいは発見できないユーザー（例：オフラインのログ分析時など）のためにのみ含まれます。
The "detail" member is a JSON string containing a human-readable explanation specific to this occurrence of the problem.
"detail" メンバーは、この問題の発生に固有の人間が読める説明を含む JSON 文字列です。
The "detail" string, if present, ought to focus on helping the client correct the problem, rather than giving debugging information.
"detail" 文字列は、存在する場合、デバッグ情報を提供するのではなく、クライアントが問題を解決するのを助けることに焦点を当てるべきです。
Consumers SHOULD NOT parse the "detail" member for information; extensions are more suitable and less error-prone ways to obtain such information.
消費者は情報を得るために "detail" メンバーをパースすべきではありません（SHOULD NOT）。そのような情報を得るには、拡張機能の方が適しており、エラーも少なくなります。
The "instance" member is a JSON string containing a URI reference that identifies the specific occurrence of the problem.
"instance" メンバーは、問題の特定の発生を識別する URI 参照を含む JSON 文字列です。
When the "instance" URI is dereferenceable, the problem details object can be fetched from it. It might also return information about the problem occurrence in other formats through use of proactive content negotiation (see [HTTP], Section 12.5.1).
"instance" URI がデレファレンス可能な場合、そこから問題の詳細オブジェクトを取得できる場合があります。また、プロアクティブ・コンテンツネゴシエーション（[HTTP] のセクション12.5.1を参照）を使用して、他の形式で問題の発生に関する情報を返すこともあります。
When the "instance" URI is not dereferenceable, it serves as a unique identifier for the problem occurrence that may be of significance to the server but is opaque to the client.
"instance" URI がデレファレンス可能でない場合、それはサーバーにとっては意味があるかもしれませんが、クライアントにとっては不透明な、問題発生の一意の識別子として機能します。
When "instance" contains a relative URI, it is resolved relative to the document's base URI, as per [URI], Section 5. However, using relative URIs can cause confusion, and they might not be handled correctly by all implementations.
"instance" に相対 URI が含まれている場合、[URI] のセクション5に従って、ドキュメントのベース URI に対して解決されます。しかし、相対 URI を使用すると混乱を招く可能性があり、すべての実装で正しく処理されるとは限りません。
For example, if the two resources "https://api.example.org/foo/ bar/123" and "https://api.example.org/widget/456" both respond with an "instance" equal to the relative URI reference "example-instance", when resolved they will identify different resources ("https://api.example.org/foo/bar/example-instance" and "https://api.example.org/widget/example-instance", respectively). As a result, it is RECOMMENDED that absolute URIs be used in "instance" when possible, and that when relative URIs are used, they include the full path (e.g., "/instances/123").
例えば、2つのリソース "https://api.example.org/foo/bar/123" と "https://api.example.org/widget/456" が両方とも相対 URI 参照 "example-instance" に等しい "instance" でレスポンスを返した場合、解決されるとそれぞれ異なるリソース（"https://api.example.org/foo/bar/example-problem" と "https://api.example.org/widget/example-problem"）を指すことになります。その結果、可能な場合は "instance" に絶対 URI を使用すること、また相対 URI を使用する場合はフルパスを含めること（例："/instances/123"）が推奨されます（RECOMMENDED）。
Problem type definitions MAY extend the problem details object with additional members that are specific to that problem type.
問題タイプの定義では、その問題タイプに固有の追加メンバーで問題の詳細オブジェクトを拡張しても構いません（MAY）。
For example, our out-of-credit problem above defines two such extensions -- "balance" and "accounts" to convey additional, problem-specific information.
例えば、上記の残高不足の問題では、追加の問題固有の情報を伝えるために "balance" と "accounts" という2つの拡張を定義しています。
Similarly, the "validation error" example defines an "errors" extension that contains a list of individual error occurrences found, with details and a pointer to the location of each.
同様に、「バリデーションエラー」の例では、見つかった個々のエラー発生のリスト、それぞれの詳細、およびその場所へのポインターを含む "errors" 拡張を定義しています。
Clients consuming problem details MUST ignore any such extensions that they don't recognize; this allows problem types to evolve and include additional information in the future.
問題の詳細を消費するクライアントは、認識できない拡張を無視しなければなりません（MUST）。これにより、問題タイプが進化し、将来的に追加情報を含めることが可能になります。
When creating extensions, problem type authors should choose their names carefully. To be used in the XML format (see Appendix B), they will need to conform to the Name rule in Section 2.3 of [XML].
拡張を作成する際、問題タイプの作成者はその名前を慎重に選択する必要があります。XML 形式（付録Bを参照）で使用するためには、[XML] のセクション2.3の Name ルールに準拠する必要があります。
When an HTTP API needs to define a response that indicates an error condition, it might be appropriate to do so by defining a new problem type.
HTTP APIがエラー条件を示すレスポンスを定義する必要がある場合、新しい問題タイプを定義することが適切な場合があります。
Before doing so, it's important to understand what they are good for and what is better left to other mechanisms.
そうする前に、それらが何に適しているのか、また何が他のメカニズムに任せるべきなのかを理解することが重要です。
Problem details are not a debugging tool for the underlying implementation; rather, they are a way to expose greater detail about the HTTP interface itself. Designers of new problem types need to carefully take into account the Security Considerations (Section 5), in particular, the risk of exposing attack vectors by exposing implementation internals through error messages.
問題の詳細は、基盤となる実装のためのデバッグツールではありません。むしろ、HTTP インターフェース自体についてのより詳細な情報を公開するための手段です。新しい問題タイプの設計者は、セキュリティに関する考慮事項（セクション5）、特にエラーメッセージを通じて実装の内部を公開することによる攻撃ベクター（攻撃経路）の露出リスクを慎重に考慮する必要があります。
Likewise, truly generic problems -- i.e., conditions that might apply to any resource on the Web -- are usually better expressed as plain status codes. For example, a "write access disallowed" problem is probably unnecessary, since a 403 Forbidden status code in response to a PUT request is self-explanatory.
同様に、真に一般的な問題、つまり、Web上の任意のリソースに適用される可能性のある条件は、通常、プレーンステータスコードとしてよりよく表現されます。たとえば、PUTリクエストに応じて403の禁止されたステータスコードは自明であるため、「書き込みアクセス許可」問題はおそらく不要です。
Finally, an application might have a more appropriate way to carry an error in a format that it already defines. Problem details are intended to avoid the necessity of establishing new "fault" or "error" document formats, not to replace existing domain-specific formats.
最後に、アプリケーションには、既に定義されている形式でエラーを伝達するためのより適切な方法がある場合があります。問題の詳細は、既存のドメイン固有の形式を置き換えるのではなく、新しい「障害」または「エラー」ドキュメント形式を確立する必要性を回避することを目的としています。
That said, it is possible to add support for problem details to existing HTTP APIs using HTTP content negotiation (e.g., using the Accept request header to indicate a preference for this format; see [HTTP], Section 12.5.1).
とはいえ、HTTPコンテンツネゴシエーションを使用して、既存のHTTP APIに問題の詳細をサポートすることができます（たとえば、この形式の優先を示すためにAccect request Headerを使用します。[http]、セクション12.5.1を参照）。
New problem type definitions MUST document:
新しい問題タイプの定義は文書化する必要があります。
1. a type URI (typically, with the "http" or "https" scheme)
1. タイプURI（通常、「HTTP」または「HTTPS」スキームを使用）
2. a title that appropriately describes it (think short)
2. 適切に説明するタイトル（短く考えてください）
3. the HTTP status code for it to be used with
3. それを使用するためのHTTPステータスコード
Problem type definitions MAY specify the use of the Retry-After response header ([HTTP], Section 10.2.3) in appropriate circumstances.
問題タイプの定義では、適切な状況では、再試行後の応答ヘッダー（[http]、セクション10.2.3）の使用を指定する場合があります。
A problem type URI SHOULD resolve to HTML [HTML5] documentation that explains how to resolve the problem.
問題タイプのURIは、問題を解決する方法を説明するHTML [HTML5]ドキュメントに解決する必要があります。
A problem type definition MAY specify additional members on the problem details object. For example, an extension might use typed links [WEB-LINKING] to another resource that machines can use to resolve the problem.
問題タイプ定義では、問題の詳細オブジェクトに追加のメンバーを指定する場合があります。たとえば、拡張機能は、マシンが問題を解決するために使用できる別のリソースに型付けされたリンク[Webリンク]を使用する場合があります。
If such additional members are defined, their names SHOULD start with a letter (ALPHA, as per [ABNF], Appendix B.1) and SHOULD comprise characters from ALPHA, DIGIT ([ABNF], Appendix B.1), and "_" (so that it can be serialized in formats other than JSON), and they SHOULD be three characters or longer.
そのような追加のメンバーが定義されている場合、彼らの名前は文字（Alpha、[ABNF]、付録B.1）から始まり、アルファ、桁（[ABNF]、付録B.1）、および「_」の文字を含む必要があります。「（JSON以外の形式でシリアル化できるように）、3文字以上である必要があります。
For example, if you are publishing an HTTP API to your online shopping cart, you might need to indicate that the user is out of credit (our example from above) and therefore cannot make the purchase.
例えば、オンラインショッピングカートの HTTP API を公開している場合、ユーザーが残高不足（上記の例）であり、そのため購入できないことを示す必要があるかもしれません。
If you already have an application-specific format that can accommodate this information, it's probably best to do that. However, if you don't, you might use one of the problem detail formats -- JSON if your API is JSON-based or XML if it uses that format.
この情報を収容できるアプリケーション固有の形式がすでにある場合は、それを使用するのがおそらく最善です。しかし、そうでない場合は、API が JSON ベースであれば JSON、その形式を使用していれば XML といった問題詳細形式のいずれかを使用できます。
To do so, you might look in the registry (Section 4.2) for an already-defined type URI that suits your purposes. If one is available, you can reuse that URI.
そのためには、レジストリ（セクション4.2）を調べて、目的に合った定義済みのタイプ URI がないか探すことができます。利用可能なものがあれば、その URI を再利用できます。
If one isn't available, you could mint and document a new type URI (which ought to be under your control and stable over time), an appropriate title and the HTTP status code that it will be used with, along with what it means and how it should be handled.
利用可能なものがない場合は、新しいタイプ URI（自身が管理し、長期間安定しているべきもの）、適切なタイトル、使用される HTTP ステータスコード、およびその意味と処理方法を新しく作成し、文書化することができます。
This specification defines the "HTTP Problem Types" registry for common, widely used problem type URIs, to promote reuse.
この仕様では、再利用を促進するために、一般的で広く使用されている問題タイプ URI のための「HTTP Problem Types」レジストリを定義します。
The policy for this registry is Specification Required, per [RFC8126], Section 4.6.
このレジストリのポリシーは、[RFC8126] のセクション4.6に従い、「仕様が必要（Specification Required）」です。
When evaluating requests, the designated expert(s) should consider community feedback, how well-defined the problem type is, and this specification's requirements. Vendor-specific, application-specific, and deployment-specific values are unable to be registered. Specification documents should be published in a stable, freely available manner (ideally located with a URL) but need not be standards.
リクエストを評価する際、指定された専門家はコミュニティのフィードバック、問題タイプがどれだけ明確に定義されているか、およびこの仕様の要求事項を考慮すべきです。ベンダー固有、アプリケーション固有、および展開固有の値は登録できません。仕様書は、安定的かつ自由に利用可能な方法（理想的には URL が付与されている）で公開されるべきですが、標準規格である必要はありません。
Registrations MAY use the prefix "https://iana.org/assignments/http-problem-types#" for the type URI. Note that those URIs may not be able to be resolved.
登録では、タイプ URI に接頭辞 "https://iana.org/assignments/http-problem-types#" を使用しても構いません（MAY）。これらの URI は解決（resolve）できない場合があることに注意してください。
The following template should be used for registration requests:
登録リクエストには以下のテンプレートを使用すべきです。
Type URI:
タイプ URI：
[a URI for the problem type]
[問題タイプの URI]
Title:
タイトル：
[a short description of the problem type]
[問題タイプの短い説明]
Recommended HTTP status code:
推奨される HTTP ステータスコード：
[what status code is most appropriate to use with the type]
[そのタイプで使用するのに最も適切なステータスコード]
Reference:
参照：
[to a specification defining the type]
[タイプを定義する仕様への参照]
See the registry at <https://iana.org/assignments/http-problem-types> for details on where to send registration requests.
登録リクエストの送信先に関する詳細は、<https://iana.org/assignments/http-problem-types> のレジストリを参照してください。
This specification registers one Problem Type, "about:blank", as follows.
この仕様では、以下のように 1 つの問題タイプ "about:blank" を登録します。
Type URI:
タイプ URI：
about:blank
about:blank
Title:
タイトル：
See HTTP Status Code
HTTP ステータスコードを参照してください
Recommended HTTP status code:
推奨される HTTP ステータスコード：
N/A
該当なし
Reference:
参照：
RFC 9457
RFC 9457
The "about:blank" URI [ABOUT], when used as a problem type, indicates that the problem has no additional semantics beyond that of the HTTP status code.
"about:blank" URI [ABOUT] を問題タイプとして使用する場合、その問題は HTTP ステータスコード以上の追加の意味を持たないことを示します。
When "about:blank" is used, the title SHOULD be the same as the recommended HTTP status phrase for that code (e.g., "Not Found" for 404, and so on), although it MAY be localized to suit client preferences (expressed with the Accept-Language request header).
"about:blank" が使用される場合、タイトルはそのコードの推奨される HTTP ステータスフレーズ（例：404 の場合は "Not Found" など）と同じであるべきです（SHOULD）。ただし、クライアントの好み（Accept-Language リクエストヘッダーで表現される）に合わせてローカライズされても構いません（MAY）。
Please note that according to how the "type" member is defined (Section 3.1), the "about:blank" URI is the default value for that member. Consequently, any problem details object not carrying an explicit "type" member implicitly uses this URI.
"type" メンバーの定義方法（セクション3.1）によれば、"about:blank" URI はそのメンバーのデフォルト値であることに注意してください。したがって、明示的な "type" メンバーを持たない問題詳細オブジェクトは、暗黙的にこの URI を使用します。
When defining a new problem type, the information included must be carefully vetted. Likewise, when actually generating a problem -- however it is serialized -- the details given must also be scrutinized.
新しい問題タイプを定義する際、そこに含まれる情報は慎重に審査されなければなりません。同様に、実際に問題を生成する際も（それがどのようにシリアル化されるにせよ）、提供される詳細は精査されなければなりません。
Risks include leaking information that can be exploited to compromise the system, access to the system, or the privacy of users of the system.
リスクには、システムの侵害、システムへのアクセス、あるいはシステムのユーザーのプライバシーを悪用するために利用されかねない情報の漏洩が含まれます。
Generators providing links to occurrence information are encouraged to avoid making implementation details such as a stack dump available through the HTTP interface, since this can expose sensitive details of the server implementation, its data, and so on.
発生情報へのリンクを提供する生成側は、HTTP インターフェースを通じてスタックダンプのような実装の詳細を提供しないようにすることが推奨されます。これらはサーバー実装やそのデータなどの機密情報を露出させる可能性があるためです。
The "status" member duplicates the information available in the HTTP status code itself, bringing the possibility of disagreement between the two. Their relative precedence is not clear, since a disagreement might indicate that (for example) an intermediary has changed the HTTP status code in transit (e.g., by a proxy or cache). Generic HTTP software (such as proxies, load balancers, firewalls, and virus scanners) are unlikely to know of or respect the status code conveyed in this member.
"status" メンバーは HTTP ステータスコード自体にある情報を重複して持っており、両者の間に不一致が生じる可能性があります。不一致がある場合、例えば仲介者（プロキシやキャッシュなど）が転送中に HTTP ステータスコードを変更したことを示している可能性があるため、どちらが優先されるかは明確ではありません。一般的な HTTP ソフトウェア（プロキシ、ロードバランサー、ファイアウォール、ウイルススキャナーなど）が、このメンバーで伝達されるステータスコードを認識したり尊重したりする可能性は低いです。
In the "application" registry under the "Media Types" registry, IANA has updated the "application/problem+json" and "application/ problem+xml" registrations to refer to this document.
「Media Types」レジストリ内の「application」レジストリにおいて、IANA は "application/problem+json" および "application/problem+xml" の登録を更新し、この文書を参照するようにしました。
IANA has created the "HTTP Problem Types" registry as specified in Section 4.2 and populated it with "about:blank" as per Section 4.2.1.
IANA は、セクション4.2で指定された通り「HTTP Problem Types」レジストリを作成し、セクション4.2.1に従って "about:blank" を登録しました。
[ABNF] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234,
DOI 10.17487/RFC5234, January 2008,
<https://www.rfc-editor.org/info/rfc5234>.
[HTTP] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
Ed., "HTTP Semantics", STD 97, RFC 9110,
DOI 10.17487/RFC9110, June 2022,
<https://www.rfc-editor.org/info/rfc9110>.
[JSON] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
Interchange Format", STD 90, RFC 8259,
DOI 10.17487/RFC8259, December 2017,
<https://www.rfc-editor.org/info/rfc8259>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>.
[RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for
Writing an IANA Considerations Section in RFCs", BCP 26,
RFC 8126, DOI 10.17487/RFC8126, June 2017,
<https://www.rfc-editor.org/info/rfc8126>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[URI] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, DOI 10.17487/RFC3986, January 2005,
<https://www.rfc-editor.org/info/rfc3986>.
[XML] Bray, T., Paoli, J., Sperberg-McQueen, C. M., Maler, E.,
and F. Yergeau, "Extensible Markup Language (XML) 1.0
(Fifth Edition)", W3C Recommendation REC-xml-20081126,
November 2008,
<https://www.w3.org/TR/2008/REC-xml-20081126/>.
[ABOUT] Moonesamy, S., Ed., "The "about" URI Scheme", RFC 6694,
DOI 10.17487/RFC6694, August 2012,
<https://www.rfc-editor.org/info/rfc6694>.
[HTML5] WHATWG, "HTML: Living Standard",
<https://html.spec.whatwg.org>.
[ISO-19757-2]
ISO, "Information technology -- Document Schema Definition
Language (DSDL) -- Part 2: Regular-grammar-based
validation -- RELAX NG", ISO/IEC 19757-2:2008, December
2008, <https://www.iso.org/standard/52348.html>.
[JSON-POINTER]
Bryan, P., Ed., Zyp, K., and M. Nottingham, Ed.,
"JavaScript Object Notation (JSON) Pointer", RFC 6901,
DOI 10.17487/RFC6901, April 2013,
<https://www.rfc-editor.org/info/rfc6901>.
[JSON-SCHEMA]
Wright, A., Ed., Andrews, H., Ed., Hutton, B., Ed., and G.
Dennis, "JSON Schema: A Media Type for Describing JSON
Documents", Work in Progress, Internet-Draft, draft-
bhutton-json-schema-01, 10 June 2022,
<https://datatracker.ietf.org/doc/html/draft-bhutton-json-
schema-01>.
[RDFA] Adida, B., Birbeck, M., McCarron, S., and I. Herman, "RDFa
Core 1.1 - Third Edition", W3C Recommendation, March 2015,
<https://www.w3.org/TR/2015/REC-rdfa-core-20150317/>.
[RFC7807] Nottingham, M. and E. Wilde, "Problem Details for HTTP
APIs", RFC 7807, DOI 10.17487/RFC7807, March 2016,
<https://www.rfc-editor.org/info/rfc7807>.
[TAG] Kindberg, T. and S. Hawke, "The 'tag' URI Scheme",
RFC 4151, DOI 10.17487/RFC4151, October 2005,
<https://www.rfc-editor.org/info/rfc4151>.
[WEB-LINKING]
Nottingham, M., "Web Linking", RFC 8288,
DOI 10.17487/RFC8288, October 2017,
<https://www.rfc-editor.org/info/rfc8288>.
[XSLT] Clark, J., Pieters, S., and H. Thompson, "Associating
Style Sheets with XML documents 1.0 (Second Edition)", W3C
Recommendation, October 2010,
<https://www.w3.org/TR/2010/REC-xml-stylesheet-20101028/>.
This section presents a non-normative JSON Schema [JSON-SCHEMA] for HTTP problem details. If there is any disagreement between it and the text of the specification, the latter prevails.
このセクションでは、HTTP 問題詳細のための参考情報（非規範的）としての JSON スキーマ [JSON-SCHEMA] を示します。もしこのスキーマと仕様の本文との間に不一致がある場合は、後者が優先されます。
# NOTE: '\' line wrapping per RFC 8792
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "An RFC 7807 problem object",
"type": "object",
"properties": {
"type": {
"type": "string",
"format": "uri-reference",
"description": "A URI reference that identifies the \
problem type."
},
"title": {
"type": "string",
"description": "A short, human-readable summary of the \
problem type."
},
"status": {
"type": "integer",
"description": "The HTTP status code \
generated by the origin server for this occurrence of the problem.",
"minimum": 100,
"maximum": 599
},
"detail": {
"type": "string",
"description": "A human-readable explanation specific to \
this occurrence of the problem."
},
"instance": {
"type": "string",
"format": "uri-reference",
"description": "A URI reference that identifies the \
specific occurrence of the problem. It may or may not yield \
further information if dereferenced."
}
}
}
HTTP-based APIs that use XML [XML] can express problem details using the format defined in this appendix.
XML [XML] を使用する HTTP ベースの API は、この付録で定義されている形式を使用して問題の詳細を表現できます。
The RELAX NG schema [ISO-19757-2] for the XML format is:
XML 形式のための RELAX NG スキーマ [ISO-19757-2] は以下の通りです。
default namespace ns = "urn:ietf:rfc:7807"
start = problem
problem =
element problem {
( element type { xsd:anyURI }?
& element title { xsd:string }?
& element detail { xsd:string }?
& element status { xsd:positiveInteger }?
& element instance { xsd:anyURI }? ),
anyNsElement
}
anyNsElement =
( element ns:* { anyNsElement | text }
| attribute * { text })*
Note that this schema is only intended as documentation and not as a normative schema that captures all constraints of the XML format. It is possible to use other XML schema languages to define a similar set of constraints (depending on the features of the chosen schema language).
このスキーマは文書化のみを目的としており、XML 形式のすべての制約を網羅する規範的なスキーマではないことに注意してください。選択したスキーマ言語の機能に応じて、他の XML スキーマ言語を使用して同様の制約セットを定義することも可能です。
The media type for this format is "application/problem+xml".
この形式のメディアタイプは "application/problem+xml" です。
Extension arrays and objects are serialized into the XML format by considering an element containing a child or children to represent an object, except for elements containing only one or more child elements named "i", which are considered arrays. For example, the example above appears in XML as follows:
拡張の配列およびオブジェクトは、子要素を持つ要素をオブジェクトとみなすことによって XML 形式にシリアル化されます。ただし、"i" という名前の1つ以上の子要素のみを含む要素は配列とみなされます。例えば、上記の例は XML では以下のようになります。
HTTP/1.1 403 Forbidden
Content-Type: application/problem+xml
Content-Language: en
<?xml version="1.0" encoding="UTF-8"?>
<problem xmlns="urn:ietf:rfc:7807">
<type>https://example.com/probs/out-of-credit</type>
<title>You do not have enough credit.</title>
<detail>Your current balance is 30, but that costs 50.</detail>
<instance>https://example.net/account/12345/msgs/abc</instance>
<balance>30</balance>
<accounts>
<i>https://example.net/account/12345</i>
<i>https://example.net/account/67890</i>
</accounts>
</problem>
This format uses an XML namespace, primarily to allow embedding it into other XML-based formats; it does not imply that it can or should be extended with elements or attributes in other namespaces. The RELAX NG schema explicitly only allows elements from the one namespace used in the XML format. Any extension arrays and objects MUST be serialized into XML markup using only that namespace.
この形式は XML 名前空間を使用していますが、これは主に他の XML ベースの形式への埋め込みを可能にするためのものです。他の名前空間の要素や属性によって拡張できること、あるいは拡張すべきであることを意味するものではありません。RELAX NG スキーマでは、XML 形式で使用される単一の名前空間の要素のみを明示的に許可しています。拡張の配列やオブジェクトは、必ずその名前空間のみを使用して XML マークアップにシリアル化されなければなりません（MUST）。
When using the XML format, it is possible to embed an XML processing instruction in the XML that instructs clients to transform the XML, using the referenced XSL Transformations (XSLT) code [XSLT]. If this code is transforming the XML into (X)HTML, then it is possible to serve the XML format, and yet have clients capable of performing the transformation display human-friendly (X)HTML that is rendered and displayed at the client. Note that when using this method, it is advisable to use XSLT 1.0 in order to maximize the number of clients capable of executing the XSLT code.
XML 形式を使用する場合、XML 内に XSL Transformations (XSLT) コード [XSLT] を参照する XML 処理命令を埋め込み、クライアントに XML の変換を指示することが可能です。そのコードによって XML が (X)HTML に変換される場合、XML 形式を提供しながら、変換を実行できるクライアントに人間にとって使いやすい (X)HTML をレンダリングして表示させることができます。なお、この手法を用いる場合、XSLT コードを実行できるクライアントの数を最大化するために、XSLT 1.0 を使用することをお勧めします。
In some situations, it can be advantageous to embed problem details in formats other than those described here. For example, an API that uses HTML [HTML5] might want to also use HTML for expressing its problem details.
状況によっては、ここで説明した以外の形式で問題の詳細を埋め込むことが有利な場合があります。例えば、HTML [HTML5] を使用する API は、問題の詳細を表現するためにも HTML を使用したいと考えるかもしれません。
Problem details can be embedded in other formats either by encapsulating one of the existing serializations (JSON or XML) into that format or by translating the model of a problem detail (as specified in Section 3) into the format's conventions.
問題の詳細を他の形式に埋め込むには、既存のシリアル化形式（JSON または XML）のいずれかをその形式の中にカプセル化するか、問題詳細のモデル（セクション3で規定）をその形式の慣習に変換するかのいずれかの方法があります。
For example, in HTML, a problem could be embedded by encapsulating JSON in a script tag:
例えば HTML では、script タグ内に JSON をカプセル化することで問題を埋め込むことができます。
<script type="application/problem+json">
{
"type": "https://example.com/probs/out-of-credit",
"title": "You do not have enough credit.",
"detail": "Your current balance is 30, but that costs 50.",
"instance": "/account/12345/msgs/abc",
"balance": 30,
"accounts": ["/account/12345",
"/account/67890"]
}
</script>
or by defining a mapping into a Resource Description Framework in Attributes (RDFa) [RDFA].
あるいは、RDFa (Resource Description Framework in Attributes) [RDFA] へのマッピングを定義することによっても可能です。
This specification does not make specific recommendations regarding embedding problem details in other formats; the appropriate way to embed them depends both upon the format in use and application of that format.
この仕様は、他の形式への問題詳細の埋め込みに関して特定の推奨を行うものではありません。適切な埋め込み方法は、使用する形式とその形式のアプリケーションの両方に依存します。
This revision has made the following changes:
この改訂では以下の変更が行われました。
* Section 4.2 introduces a registry of common problem type URIs
* セクション4.2において、共通の問題タイプ URI のレジストリを導入しました。
* Section 3 clarifies how multiple problems should be treated
* セクション3において、複数の問題をどのように扱うべきかを明確にしました。
* Section 3.1.1 provides guidance for using type URIs that cannot be dereferenced
* セクション3.1.1において、デレファレンスできないタイプ URI を使用するためのガイダンスを提供しました。
The authors would like to thank Jan Algermissen, Subbu Allamaraju, Mike Amundsen, Roy Fielding, Eran Hammer, Sam Johnston, Mike McCall, Julian Reschke, and James Snell for their comments and suggestions.
著者は、コメントや提案をいただいた Jan Algermissen、Subbu Allamaraju、Mike Amundsen、Roy Fielding、Eran Hammer、Sam Johnston、Mike McCall、Julian Reschke、James Snell の各氏に感謝いたします。
Mark Nottingham
Prahran
Australia
Email: mnot@mnot.net
URI: https://www.mnot.net/
Erik Wilde
Email: erik.wilde@dret.net
URI: http://dret.net/netdret/
Sanjay Dalal
United States of America
Email: sanjay.dalal@cal.berkeley.edu
URI: https://github.com/sdatspun2