API Error Response Writing — RFC 7807 & Error Design
Practice writing API error response schemas using RFC 7807 Problem Details, error code design, and human-readable vs. machine-readable error patterns.
0 / 5 completed
1 / 5
What is RFC 7807 'Problem Details' and why is it used in API error responses?
RFC 7807 defines a standard 'application/problem+json' content type with fields: type (URI identifying the error class), title (human-readable summary), status (HTTP status code), detail (human-readable explanation of this specific occurrence), instance (URI identifying this specific error occurrence). Using it means consumers can handle errors uniformly instead of parsing custom error formats per API.
2 / 5
What is the difference between the 'title' and 'detail' fields in an RFC 7807 error response?
Title: 'Insufficient account balance' — same for every instance of this error type. Detail: 'Your balance is $4.50 but the transaction requires $12.00' — specific to this occurrence. Clients can use title for error categorisation and detail for displaying context-specific messages to users. The type URI is the true machine-readable identifier; title is its human-readable companion.
3 / 5
What is the recommended design pattern for API error codes to support both human and machine consumers?
Best practice: combine a stable machine-readable code (ACCOUNT_LOCKED, VALIDATION_FAILED) with a human-readable message. Machines key on the code — never on message text, which may change. Example: { 'code': 'RATE_LIMIT_EXCEEDED', 'message': 'You have exceeded 100 requests per minute. Retry after 2024-03-15T14:31:00Z.', 'retryAfter': '2024-03-15T14:31:00Z' }. Separating the code from the message lets you localise messages without breaking client logic.
4 / 5
What is the 'instance' field in RFC 7807 used for?
instance: a URI (often a URN) pointing to the specific error occurrence. Example: 'instance': '/errors/logs/550e8400-e29b-41d4-a716-446655440000' or 'instance': 'urn:uuid:550e8400-e29b-41d4-a716-446655440000'. This lets a user copy their instance URI when contacting support, and support staff can look up the exact error context. It is optional but highly recommended for debuggability.
5 / 5
When documenting API error responses in OpenAPI, what is the recommended practice for the 'type' URI in RFC 7807?
Best practice: 'type': 'https://api.example.com/errors/insufficient-funds' — a real URL consumers can visit to read about the error. The page should explain: what causes it, how to reproduce it, how to resolve it, and example responses. 'about:blank' is valid RFC 7807 (it means the title/status alone describe the problem) but loses the self-documenting benefit. Generic types should only be used when no additional documentation is needed.