TL;DR (要約)
RFC 9457 (HTTP API のための問題詳細) は、API エラー応答の標準フォーマットです。これは、カスタムエラーフォーマットを、type、title、status、detail、instance という一貫した構造に置き換えます。Modern PetstoreAPI は、適切なコンテンツネゴシエーションと検証の詳細を備えたすべてのエラー応答で RFC 9457 を実装しています。
はじめに
あなたの API はエラーを返します。その応答はどのようなものでしょうか？もしあなたがほとんどの API と同じなら、独自のフォーマットを発明したことでしょう。
{"error": "Invalid email"}
{"message": "Not found", "code": 404}
{"success": false, "errors": ["Email required"]}
すべての API には異なるエラーフォーマットがあります。クライアントは、各 API に対してカスタムエラー処理を行う必要があります。エラーを解析したり、ユーザーに表示したり、デバッグのためにログに記録したりするための標準的な方法はありません。
RFC 9457 はこれを解決します。これは、API がエラーを返す方法を定義する IETF 標準です。独自のフォーマットを発明する代わりに、クライアントがすでに理解している実績のある標準を使用します。
以前の Swagger Petstore は、一貫性のないカスタムエラーフォーマットを使用していました。Modern PetstoreAPI は、すべてのエラー応答で RFC 9457 を実装し、構造化された機械可読なエラー詳細を提供します。
このガイドでは、RFC 9457 が何か、それを正しく実装する方法、そして Modern PetstoreAPI がすべてのエラー応答でそれを使用する方法について学びます。
API エラーの問題
RFC 9457 以前は、すべての API が独自のエラーフォーマットを発明していました。
一般的なエラーフォーマットのバリエーション
フォーマット 1: シンプルなメッセージ
{"error": "User not found"}
フォーマット 2: コードとメッセージ
{"code": "USER_NOT_FOUND", "message": "User not found"}
フォーマット 3: ネストされた構造
{
"success": false,
"error": {
"type": "NotFound",
"message": "User not found"
}
}
フォーマット 4: エラーの配列
{
"errors": [
{"field": "email", "message": "Invalid email"}
]
}
カスタムフォーマットの問題点
1. 一貫性がない: クライアントは、各 API に対してカスタム解析を行う必要があります。
2. 情報の欠落: 一部のフォーマットにはエラーコードがなく、一部には詳細がなく、一部には両方がありません。
3. 機械可読な構造がない: プログラムでエラーを処理するのが困難です。
4. 国際化の不備: エラーメッセージが英語でハードコードされています。
5. バリデーションエラーの標準がない: 各 API はフィールドレベルのエラーを異なる方法で処理します。
RFC 9457 とは？
RFC 9457（2023年7月発行）は、「HTTP API のための問題詳細」を定義しています。これは、API がエラー応答を構造化する方法を規定する IETF 標準です。
主な機能
標準メディアタイプ: application/problem+json（または application/problem+xml）
一貫した構造: すべてのエラーが同じフォーマットに従います
機械可読: クライアントはプログラムでエラーを解析できます
拡張可能: 互換性を維持しながらカスタムフィールドを追加できます
HTTP 対応: HTTP ステータスコードと統合します
RFC 9457 vs カスタムエラー
カスタムエラー:
{"error": "Email is required"}
RFC 9457 エラー:
{
"type": "https://petstoreapi.com/errors/validation-error",
"title": "Validation Error",
"status": 400,
"detail": "The request contains invalid data",
"instance": "/pets",
"errors": [
{
"field": "email",
"message": "Email is required"
}
]
}
RFC 9457 バージョンは以下を提供します。
- ドキュメント用のエラータイプ URL
- 人間が読めるタイトル
- HTTP ステータスコード
- 詳細な説明
- エラーの原因となったリクエストパス
- フィールドレベルの検証詳細
RFC 9457 の構造解説
RFC 9457 は 5 つの標準フィールドを定義し、カスタム拡張を許可します。
標準フィールド
1. type (文字列, 必須)
エラータイプを識別する URI 参照。人間が読めるドキュメントを指すべきです。
"type": "https://petstoreapi.com/errors/validation-error"
省略された場合、about:blank がデフォルトとなります。
2. title (文字列, 必須)
エラータイプの短く人間が読める要約。発生ごとに変更すべきではありません。
"title": "Validation Error"
3. status (数値, 必須)
HTTP ステータスコード。クライアントがヘッダーを解析する必要がないよう便宜的に含まれています。
"status": 400
4. detail (文字列, オプション)
このエラーの発生に特化した人間が読める説明。
"detail": "The email field must be a valid email address"
5. instance (文字列, オプション)
エラーの特定の発生を識別する URI 参照。多くの場合、リクエストパスです。
"instance": "/pets/019b4132-70aa-764f-b315-e2803d882a24"
カスタム拡張
追加のコンテキストのためにカスタムフィールドを追加できます。
{
"type": "https://petstoreapi.com/errors/rate-limit-exceeded",
"title": "Rate Limit Exceeded",
"status": 429,
"detail": "You have exceeded the rate limit of 100 requests per minute",
"instance": "/pets",
"retryAfter": 42,
"limit": 100,
"remaining": 0,
"resetAt": "2026-03-13T10:30:00Z"
}
Modern PetstoreAPI はどのように RFC 9457 を実装しているか
Modern PetstoreAPI は、すべてのエラー応答で RFC 9457 を使用しています。
例 1: リソースが見つかりません
GET /pets/invalid-id
404 Not Found
Content-Type: application/problem+json
{
"type": "https://docs.petstoreapi.com/errors/not-found",
"title": "Resource Not Found",
"status": 404,
"detail": "The requested pet does not exist",
"instance": "/pets/invalid-id"
}
例 2: 認証エラー
GET /pets
401 Unauthorized
Content-Type: application/problem+json
{
"type": "https://docs.petstoreapi.com/errors/unauthorized",
"title": "Authentication Required",
"status": 401,
"detail": "Valid authentication credentials are required to access this resource",
"instance": "/pets"
}
例 3: レート制限超過
GET /pets
429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 60
{
"type": "https://docs.petstoreapi.com/errors/rate-limit-exceeded",
"title": "Rate Limit Exceeded",
"status": 429,
"detail": "You have exceeded the rate limit of 100 requests per minute",
"instance": "/pets",
"limit": 100,
"remaining": 0,
"resetAt": "2026-03-13T10:31:00Z"
}
すべてのエラータイプについては、Modern PetstoreAPI エラー処理ドキュメントを参照してください。
RFC 9457 を使用した検証エラー
検証エラーにはフィールドレベルの詳細が必要です。RFC 9457 はこのためのカスタム拡張を許可しています。
Modern PetstoreAPI の検証フォーマット
POST /pets
400 Bad Request
Content-Type: application/problem+json
{
"type": "https://docs.petstoreapi.com/errors/validation-error",
"title": "Validation Error",
"status": 400,
"detail": "The request contains 2 validation errors",
"instance": "/pets",
"errors": [
{
"field": "name",
"message": "Name is required",
"code": "REQUIRED_FIELD"
},
{
"field": "species",
"message": "Species must be one of: DOG, CAT, BIRD, FISH, REPTILE, OTHER",
"code": "INVALID_ENUM_VALUE",
"rejectedValue": "DRAGON"
}
]
}
主要なポイント
errors 配列: フィールドレベルの検証詳細を含みます
field: 無効なフィールドへの JSON パス
message: 人間が読めるエラーメッセージ
code: 機械が読めるエラーコード
rejectedValue: 拒否された値（オプション）
このフォーマットにより、クライアントは以下のことが可能になります。
- フォームにフィールドレベルのエラーを表示する
- 無効なフィールドを強調表示する
- 特定のエラーメッセージを提供する
- プログラムでエラーを処理する
Apidog を使ったエラー応答のテスト
Apidog は RFC 9457 準拠のテストを支援します。
テストケース: 検証エラー
// Apidog test script
pm.test("Returns RFC 9457 error format", () => {
const response = pm.response.json();
// Check required fields
pm.expect(response).to.have.property("type");
pm.expect(response).to.have.property("title");
pm.expect(response).to.have.property("status");
// Check status matches HTTP status
pm.expect(response.status).to.equal(pm.response.code);
// Check content type
pm.expect(pm.response.headers.get("Content-Type"))
.to.include("application/problem+json");
});
pm.test("Validation errors include field details", () => {
const response = pm.response.json();
pm.expect(response).to.have.property("errors");
pm.expect(response.errors).to.be.an("array");
response.errors.forEach(error => {
pm.expect(error).to.have.property("field");
pm.expect(error).to.have.property("message");
});
});
テストケース: エラータイプ URL
pm.test("Error type URL is accessible", async () => {
const response = pm.response.json();
const typeUrl = response.type;
// Verify type URL returns documentation
const docResponse = await pm.sendRequest(typeUrl);
pm.expect(docResponse.code).to.equal(200);
});
カスタムエラーフォーマットからの移行
カスタムエラーフォーマットを使用している場合、RFC 9457 への移行方法は次のとおりです。
ステップ 1: Content-Type ヘッダーを追加する
application/problem+json を返し始めます。
Content-Type: application/problem+json
ステップ 2: 既存のフィールドをマッピングする
カスタムフォーマットを RFC 9457 にマッピングします。
移行前:
{
"error": "USER_NOT_FOUND",
"message": "User not found"
}
移行後:
{
"type": "https://api.example.com/errors/user-not-found",
"title": "User Not Found",
"status": 404,
"detail": "User not found"
}
ステップ 3: 両方のフォーマットをサポートする（移行期間）
コンテンツネゴシエーションを使用して両方のフォーマットをサポートします。
Accept: application/json → カスタムフォーマットを返す
Accept: application/problem+json → RFC 9457 フォーマットを返す
ステップ 4: カスタムフォーマットを非推奨にする
クライアントが移行した後、カスタムフォーマットを非推奨にし、デフォルトで RFC 9457 を返します。
まとめ
RFC 9457 は、API エラー応答のための標準フォーマットを提供します。これは、カスタムエラーフォーマットを、クライアントがプログラムで解析できる一貫した機械可読な構造に置き換えます。
Modern PetstoreAPI は、すべてのエラー応答で RFC 9457 を実装しており、適切な検証詳細、エラータイプ URL、および HTTP ステータスコードを使用してエラーを正しく構造化する方法を示しています。
Apidog を使用して、RFC 9457 準拠をテストし、エラー構造を検証し、API が適切なエラー応答を返すことを確認してください。
よくある質問
RFC 9457 は REST API に必須ですか？
いいえ、しかし推奨される標準です。RFC 9457 を使用すると、API の一貫性が高まり、クライアントが統合しやすくなります。
RFC 9457 を XML と一緒に使用できますか？
はい、RFC 9457 は JSON（application/problem+json）と XML（application/problem+xml）の両方のフォーマットを定義しています。
常に 5 つの標準フィールドすべてを含めるべきですか？
type、title、status は必須です。detail と instance はオプションですが、より良いエラーコンテキストのために推奨されます。
RFC 9457 応答にカスタムフィールドを追加できますか？
はい、RFC 9457 は拡張可能です。追加のコンテキストのために、errors、retryAfter、traceId などのカスタムフィールドを追加できます。
RFC 9457 で検証エラーを処理するにはどうすればよいですか？
フィールドレベルの詳細を含むカスタムの errors 配列を追加します。Modern PetstoreAPI は、その検証エラー応答でこのパターンを示しています。
エラータイプ URL は何を指すべきですか？
エラータイプ、考えられる原因、および修正方法を説明する人間が読めるドキュメントを指すべきです。
RFC 9457 を使用する際に HTTP ステータスコードを変更する必要がありますか？
いいえ、RFC 9457 は標準の HTTP ステータスコードと連携します。応答の status フィールドは HTTP ステータスコードと一致する必要があります。
RFC 9457 準拠をテストするにはどうすればよいですか？
Apidog を使用して、エラー応答構造を検証し、必須フィールドを確認し、コンテンツタイプが RFC 9457 の仕様と一致していることを確認してください。