Problem Details for HTTP APIs
Problem Details (RFC 7807) standardize HTTP error bodies as application/problem+json objects with type, title, status, detail, and optional instance fields. Clients parse one predictable shape across services instead of guessing whether errors live in message, error, or errors arrays.
Technical Architecture & Deep-Dive
A 422 response might return { "type": "https://api.example.com/problems/validation", "title": "Validation failed", "status": 422, "detail": "email is invalid" }. Extensions add field-specific issues under a stable namespace.
BFF layers map chaotic upstream errors into Problem Details before they reach mobile apps. That keeps error payloads small, localizable, and easy to log while hiding provider stack traces and verbose debug blobs.
Key Architectural Benefits
RFC 7807 Problem
{
"type": "https://api.example.com/problems/not-found",
"title": "Resource not found",
"status": 404,
"detail": "User u_123 does not exist."
}Implement Problem Details for HTTP APIs at the Edge
Deploy lightweight API aggregation, edge caching, and secret injection in minutes without Docker containers or complex servers.
Frequently Asked Questions
Q:Should Problem Details replace GraphQL errors?
GraphQL keeps its errors array for query failures. REST and BFF HTTP layers use Problem Details for transport-level failures.
Related Architecture Concepts
GraphQL errors describe query or resolver failures in an errors array alongside optional data when partial results are allowed. Each error includes message, path, locations, and extensions for codes, which differs from REST where non-2xx HTTP status often means no body convention at all.
An API response envelope is a wrapper object around the actual data, typically containing fields like data, meta, errors, and pagination. Envelopes give every response a consistent outer structure, making it easier to handle errors and paging uniformly.
The Idempotency-Key header lets clients supply a unique token, often a UUID, on mutating requests so the server recognizes safe retries. If the network drops after a payment or signup POST, resubmitting with the same key returns the original result instead of creating duplicate charges or records.