Problem Details for HTTP APIs (RFC 9457)

Best Practice: Problem Details for HTTP APIs (RFC 9457)

Problem Details defines a standard JSON (and XML) structure for returning machine-readable errors from HTTP APIs. Published as RFC 7807 in 2016 and updated by RFC 9457 in 2023, it specifies the media type application/problem+json and a set of members: type (a URI identifying the problem kind), title (a short human summary), status (the HTTP status code), detail (a human-readable explanation of this occurrence), and instance (a URI for this specific occurrence). It matters because every API otherwise invents its own error shape, forcing clients to write bespoke parsing for each integration. A shared error contract makes failures predictable and debuggable.

Step-by-Step Implementation Guidance

1. Adopt application/problem+json as the content type for all error responses.
2. Define stable type URIs for each category of error your API can return; document them.
3. Always set status to match the HTTP status code and keep title constant per type.
4. Put per-request specifics in detail and a request or resource identifier in instance.
5. Add domain-specific extension members (for example invalid-params) as needed.
6. Avoid leaking sensitive internals (stack traces, SQL) in detail.
7. Apply the format uniformly across all endpoints and document it in your API spec.

Common Mistakes Teams Make When Ignoring This Practice

• Inventing a different error shape per endpoint or service.
• Returning HTTP 200 with an error body, breaking client error handling.
• Putting human-only prose where clients need a stable, machine-readable type.
• Leaking stack traces and internal identifiers in error details.
• Reusing one generic error for many distinct failure causes.

Tools and Techniques That Support This Practice

• Framework support: Spring (ProblemDetail), ASP.NET Core (ProblemDetails), Hapi/Express middleware.
• OpenAPI to document the problem+json schema per error.
• Spectral rules to enforce consistent error responses.
• API gateways that can normalize errors into the format.

How This Practice Applies to Different Migration Types

• Cloud Migration: A uniform error contract behind a gateway hides which backend produced a failure.
• Database Migration: Stable error types let clients handle constraint or availability errors gracefully during cutover.
• SaaS Migration: Consuming a provider that emits problem+json simplifies error handling in integration code.
• Codebase Migration: Standardizing on RFC 9457 during a rewrite replaces inconsistent legacy error formats.

Checklist

• Errors returned as application/problem+json.
• Stable type URIs defined and documented per error.
• status field matches the HTTP status code.
• detail and instance carry per-occurrence context.
• No sensitive internals leaked in errors.
• Format applied uniformly across endpoints.
• Error schemas documented in the API spec.