[要約] RFC 9457は、HTTP APIのエラー詳細を機械可読な形式で伝達し、新しいエラー応答形式を定義する必要を避けるための「問題詳細」を定義する。RFC 7807を廃止する。
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応答コンテンツのエラーの機械可読の詳細を伝える「問題の詳細」を定義します。
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.
著作権（c）2023 IETF Trustおよび文書著者として特定された人。無断転載を禁じます。
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ドキュメント（https://trustee.ietf.org/license-info）に関連するIETF Trustの法的規定の対象となります。この文書に関するあなたの権利と制限を説明するので、これらの文書を注意深く確認してください。このドキュメントから抽出されたコードコンポーネントには、セクション4.Eで説明されている法的規定のセクション4.Eで説明されており、改訂されたBSDライセンスで説明されている保証なしで提供されるように、改訂されたBSDライセンステキストを含める必要があります。
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）は、エラーに関する十分な情報を常に伝えることはできません。Webブラウザーを使用する人間は、しばしば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".
その欠点に対処するために、この仕様では、Simple 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の禁止状態コードを使用して、応答の一般的なセマンティクスの一般的な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ドキュメントとしてシリアル化すると、「アプリケーション/問題JSON」メディアタイプを使用します。付録Bは、「アプリケーション/問題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を参照してください。特に、人間の読み取り可能な文字列（タイトルや説明など）に使用される言語は、Accect-Language Request Headerフィールド（[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", "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ドキュメントでシリアル化すると、その形式は「アプリケーション/問題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.
ここで、クレジット外の問題（そのタイプで識別）は、「タイトル」の403の理由を示し、「インスタンス」との特定の問題の発生を識別し、「詳細」で発生固有の詳細を提供し、2つの拡張機能を追加します。：「残高」はアカウントの残高を伝え、「アカウント」はアカウントを補充できるリンクをリストします。
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].
ここでの架空の問題タイプは、各検証エラーの詳細を説明する「エラー」拡張機能を定義します。各メンバーは、JSONポインター[JSON-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が同じタイプを共有しない複数の問題に遭遇する場合、最も関連性のあるまたは緊急の問題を応答で表すことをお勧めします。複数の異なるタイプを伝える一般的な「バッチ」問題タイプを作成することは可能ですが、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が許可されているように、クライアントが受け入れてリストしなかったとしても、APIは「アプリケーション/問題JSON」タイプで応答したことに注意してください（[HTTP]のセクション12.5.1を参照）。
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.
問題の詳細オブジェクトには、次のメンバーを持つことができます。メンバーの値タイプが指定されたタイプと一致しない場合、メンバーは無視する必要があります。つまり、メンバーが存在していないかのように処理が続きます。
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.
「タイプ」メンバーは、問題タイプを識別するURI参照[URI]を含むJSON文字列です。消費者は、問題タイプの主要な識別子として「タイプ」URI（必要に応じて）を使用する必要があります。
When this member is not present, its value is assumed to be "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]を使用）。ただし、開発者に情報を提供する場合（たとえば、デバッグツールが使用されている場合）、消費者はタイプのURIを自動的に抑制すべきではありません。
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.
「タイプ」に相対URIが含まれている場合、[URI]に従って、ドキュメントのベースURIに関連して解決されます。セクション5によると、相対的な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リファレンス「例と問題」、解決すると、異なるリソースが識別されます（ "https://api.example.org/foo/bar/example-problem"および "https://api.example.org/widget/それぞれ例の例」、それぞれ）。その結果、可能な場合は「タイプ」で絶対的なURIを使用し、相対URIを使用する場合、フルパス（ "/type/123"）を含めることをお勧めします。
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.
「ステータス」メンバーは、問題の発生のためにOrigin Serverによって生成された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.
「ステータス」メンバーは、存在する場合、アドバイザリーのみです。消費者の利便性に使用されるHTTPステータスコードを伝えます。ジェネレーターは、実際のHTTP応答で同じステータスコードを使用して、この形式がまだ正しく動作していると理解していない一般的なHTTPソフトウェアを保証する必要があります。その使用に関するさらなる警告については、セクション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情報なしでメッセージのコンテンツが持続したときに何であるかを判断できます。一般的なHTTPソフトウェアは引き続きHTTPステータスコードを使用します。
The "title" member is a JSON string containing a short, human-readable summary of the problem type.
「タイトル」メンバーは、問題タイプの短い人間が読み取る可能性のある要約を含む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を参照）。
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).
「タイトル」文字列はアドバイザリーであり、タイプのURIのセマンティクスを知らず、発見することができないユーザーにのみ含まれています（たとえば、オフラインログ分析中）。
The "detail" member is a JSON string containing a human-readable explanation specific to this occurrence of the problem.
「詳細」メンバーは、問題のこの発生に固有の人間が読むことができる説明を含むJSON文字列です。
The "detail" string, if present, ought to focus on helping the client correct the problem, rather than giving debugging information.
「詳細」文字列は、存在する場合、デバッグ情報を提供するのではなく、クライアントが問題を修正するのを助けることに焦点を当てるべきです。
Consumers SHOULD NOT parse the "detail" member for information; extensions are more suitable and less error-prone ways to obtain such information.
消費者は、情報の「詳細」メンバーを解析しないでください。拡張機能は、そのような情報を取得するためのより適切でエラーが発生しない方法です。
The "instance" member is a JSON string containing a URI reference that identifies the specific occurrence of the problem.
「インスタンス」メンバーは、問題の特定の発生を識別する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).
「インスタンス」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.
「インスタンス」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.
「インスタンス」に相対URIが含まれている場合、[URI]に従って、ドキュメントのベースURIに関連して解決されます。セクション5によると、相対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リファレンス「instance」、解決すると、異なるリソースが識別されます（ "https://api.example.org/foo/bar/example-instance"および "https://api.example.org/widget/それぞれのインスタンス "、それぞれ）。その結果、可能な場合は「インスタンス」で絶対的なURIを使用し、相対URIを使用するとフルパス（ "/instances/123"など）が含まれることが推奨されます。
Problem type definitions MAY extend the problem details object with additional members that are specific to that problem type.
問題タイプの定義は、問題のタイプに固有の追加メンバーで問題の詳細オブジェクトを拡張する場合があります。
For example, our out-of-credit problem above defines two such extensions -- "balance" and "accounts" to convey additional, problem-specific information.
たとえば、上記のクレジット外の問題は、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.
同様に、「検証エラー」の例は、詳細とそれぞれの位置へのポインターを含む個々のエラー発生のリストを含む「エラー」拡張機能を定義します。
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.
問題の詳細を消費するクライアントは、認識していない拡張機能を無視する必要があります。これにより、問題の種類が進化し、将来の追加情報を含めることができます。
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の名前ルールに準拠する必要があります。
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.
そのためには、あなたの目的に合ったすでに定義されたタイプのURIをレジストリ（セクション4.2）に調べることができます。利用可能な場合は、その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問題タイプ」レジストリを定義します。
The policy for this registry is Specification Required, per [RFC8126], Section 4.6.
このレジストリのポリシーは、[RFC8126]、セクション4.6に従って、仕様が必要です。
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#」を使用する場合があります。それらのurisは解決できないかもしれないことに注意してください。
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.
この仕様は、次のように、「About：About：blank」タイプのタイプを登録します。
Type URI:
タイプURI：
about:blank
概要：空白
Title:
タイトル：
See HTTP Status Code
HTTPステータスコードを参照してください
Recommended HTTP status code:
推奨されるHTTPステータスコード：
N/A
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では「見つかりません」など）と同じである必要がありますが、クライアントの好みに合わせてローカライズされる場合があります（表現されますAccept-Language Requestヘッダー付き）。
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.
「タイプ」メンバーがどのように定義されているか（セクション3.1）によれば、「About：blank」URIはそのメンバーのデフォルト値であることに注意してください。その結果、明示的な「タイプ」メンバーを運ばないオブジェクトの詳細は、この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.
「ステータス」メンバーは、HTTPステータスコード自体で利用可能な情報を複製し、2つの間に不一致の可能性をもたらします。意見の相違は（たとえば）仲介者が輸送中に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.
「メディアタイプ」レジストリの「アプリケーション」レジストリでは、IANAは「アプリケーション/問題JSON」および「アプリケーション/問題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問題タイプ」レジストリを作成し、セクション4.2.1に従って「Arout：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形式のリラックス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".
この形式のメディアタイプは「アプリケーション/問題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:
拡張アレイとオブジェクトは、アレイと見なされる「I」という名前の1つ以上の子要素のみを含む要素のみを除き、オブジェクトを表すために子供または子供を含む要素を考慮することにより、XML形式にシリアル化されます。たとえば、上記の例は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形式で使用される1つの名前空間の要素のみを明示的に許可します。任意の拡張機能とオブジェクトは、その名前空間のみを使用してXMLマークアップにシリアル化する必要があります。
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形式を使用する場合、参照されたXSL変換（XSLT）コード[XSLT]を使用して、クライアントにXMLを変換するように指示するXMLにXML処理命令を埋め込むことができます。このコードがXMLを（X）HTMLに変換している場合、XML形式を提供しているが、クライアントにレンダリングおよび表示されるTransformation Display Displayを実行できるクライアントを存在させることができます。この方法を使用する場合、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では、スクリプトタグに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）[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では、一般的な問題タイプのurisのレジストリを紹介します
* 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