TL;DR
RFC 9457 (Problem Details for HTTP APIs) is the standard format for API error responses. It replaces custom error formats with a consistent structure: type, title, status, detail, and instance. Modern PetstoreAPI implements RFC 9457 across all error responses with proper content negotiation and validation details.
Introduction
Your API returns an error. What does the response look like? If you’re like most APIs, you invented your own format:
{"error": "Invalid email"}
{"message": "Not found", "code": 404}
{"success": false, "errors": ["Email required"]}
Every API has a different error format. Clients need custom error handling for each API. There’s no standard way to parse errors, display them to users, or log them for debugging.
RFC 9457 solves this. It’s an IETF standard that defines how APIs should return errors. Instead of inventing your own format, you use a proven standard that clients already understand.
The old Swagger Petstore used custom error formats with no consistency. Modern PetstoreAPI implements RFC 9457 across all error responses, providing structured, machine-readable error details.
In this guide, you’ll learn what RFC 9457 is, how to implement it correctly, and how Modern PetstoreAPI uses it for all error responses.
The API Error Problem
Before RFC 9457, every API invented its own error format.
Common Error Format Variations
Format 1: Simple message
{"error": "User not found"}
Format 2: Code and message
{"code": "USER_NOT_FOUND", "message": "User not found"}
Format 3: Nested structure
{
"success": false,
"error": {
"type": "NotFound",
"message": "User not found"
}
}
Format 4: Array of errors
{
"errors": [
{"field": "email", "message": "Invalid email"}
]
}
Problems with Custom Formats
1. No consistency: Clients need custom parsing for each API.
2. Missing information: Some formats lack error codes, some lack details, some lack both.
3. No machine-readable structure: Hard to programmatically handle errors.
4. Poor internationalization: Error messages are hardcoded in English.
5. No standard for validation errors: Each API handles field-level errors differently.
What Is RFC 9457?
RFC 9457 (published July 2023) defines “Problem Details for HTTP APIs.” It’s an IETF standard that specifies how APIs should structure error responses.
Key Features
Standard media type: application/problem+json (or application/problem+xml)
Consistent structure: All errors follow the same format
Machine-readable: Clients can parse errors programmatically
Extensible: You can add custom fields while maintaining compatibility
HTTP-aware: Integrates with HTTP status codes
RFC 9457 vs Custom Errors
Custom error:
{"error": "Email is required"}
RFC 9457 error:
{
"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"
}
]
}
The RFC 9457 version provides:
- Error type URL for documentation
- Human-readable title
- HTTP status code
- Detailed explanation
- Request path that caused the error
- Field-level validation details
RFC 9457 Structure Explained
RFC 9457 defines five standard fields and allows custom extensions.
Standard Fields
1. type (string, required)
A URI reference identifying the error type. Should point to human-readable documentation.
"type": "https://petstoreapi.com/errors/validation-error"
If omitted, defaults to about:blank.
2. title (string, required)
A short, human-readable summary of the error type. Should not change between occurrences.
"title": "Validation Error"
3. status (number, required)
The HTTP status code. Included for convenience so clients don’t need to parse headers.
"status": 400
4. detail (string, optional)
A human-readable explanation specific to this occurrence of the error.
"detail": "The email field must be a valid email address"
5. instance (string, optional)
A URI reference identifying the specific occurrence of the error. Often the request path.
"instance": "/pets/019b4132-70aa-764f-b315-e2803d882a24"
Custom Extensions
You can add custom fields for additional context:
{
"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"
}
How Modern PetstoreAPI Implements RFC 9457
Modern PetstoreAPI uses RFC 9457 for all error responses.
Example 1: Resource Not Found
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"
}
Example 2: Authentication Error
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"
}
Example 3: Rate Limit Exceeded
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"
}
See the Modern PetstoreAPI error handling documentation for all error types.
Validation Errors with RFC 9457
Validation errors need field-level details. RFC 9457 allows custom extensions for this.
Modern PetstoreAPI Validation Format
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"
}
]
}
Key Points
errors array: Contains field-level validation details
field: The JSON path to the invalid field
message: Human-readable error message
code: Machine-readable error code
rejectedValue: The value that was rejected (optional)
This format allows clients to:
- Display field-level errors in forms
- Highlight invalid fields
- Provide specific error messages
- Handle errors programmatically
Testing Error Responses with Apidog
Apidog helps you test RFC 9457 compliance.
Test Case: Validation Error
// 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");
});
});
Test Case: Error Type URLs
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);
});
Migration from Custom Error Formats
If you’re using custom error formats, here’s how to migrate to RFC 9457.
Step 1: Add Content-Type Header
Start returning application/problem+json:
Content-Type: application/problem+json
Step 2: Map Existing Fields
Map your custom format to RFC 9457:
Before:
{
"error": "USER_NOT_FOUND",
"message": "User not found"
}
After:
{
"type": "https://api.example.com/errors/user-not-found",
"title": "User Not Found",
"status": 404,
"detail": "User not found"
}
Step 3: Support Both Formats (Transition Period)
Use content negotiation to support both formats:
Accept: application/json → Returns custom format
Accept: application/problem+json → Returns RFC 9457 format
Step 4: Deprecate Custom Format
After clients migrate, deprecate the custom format and return RFC 9457 by default.
Conclusion
RFC 9457 provides a standard format for API error responses. It replaces custom error formats with a consistent, machine-readable structure that clients can parse programmatically.
Modern PetstoreAPI implements RFC 9457 across all error responses, demonstrating how to structure errors correctly with proper validation details, error type URLs, and HTTP status codes.
Use Apidog to test RFC 9457 compliance, validate error structures, and ensure your API returns proper error responses.
FAQ
Is RFC 9457 required for REST APIs?
No, but it’s the recommended standard. Using RFC 9457 makes your API more consistent and easier for clients to integrate.
Can I use RFC 9457 with XML?
Yes, RFC 9457 defines both JSON (application/problem+json) and XML (application/problem+xml) formats.
Should I always include all five standard fields?
type, title, and status are required. detail and instance are optional but recommended for better error context.
Can I add custom fields to RFC 9457 responses?
Yes, RFC 9457 is extensible. You can add custom fields like errors, retryAfter, or traceId for additional context.
How do I handle validation errors with RFC 9457?
Add a custom errors array with field-level details. Modern PetstoreAPI shows this pattern in its validation error responses.
What should the error type URL point to?
It should point to human-readable documentation explaining the error type, possible causes, and how to fix it.
Do I need to change HTTP status codes when using RFC 9457?
No, RFC 9457 works with standard HTTP status codes. The status field in the response should match the HTTP status code.
How do I test RFC 9457 compliance?
Use Apidog to validate error response structure, check required fields, and verify content types match RFC 9457 specifications.
