Standardizing HTTP API Error Responses with RFC 7807 Problem Details

When an API request fails, returning a proper HTTP error status (e.g., 409 or 500) is a good start, but the response body often lacks sufficient detail for developers to understand or resolve the problem. Different APIs use custom error formats, forcing developers to write bespoke parsing logic or intervene manually.

The IETF's RFC 7807 "Problem Details for HTTP APIs" proposes a standardized JSON or XML payload that conveys error information in a uniform way, making it easier for generic HTTP clients to interpret and handle errors across disparate services.

Why a standard format is useful

Clients can automatically parse and present detailed error information without prior knowledge of a specific API.

APIs can emit errors more safely, knowing that identifiers remain stable even if human‑readable messages change.

Custom client libraries can filter and react to specific error types using a shared logic layer.

Proposed error format

RFC 7807 defines the following fields (all optional, though type is strongly recommended): type: a URI that identifies the error type. title: a short, human‑readable summary. detail: a longer human‑readable explanation. status: the HTTP status code used. instance: a URI that identifies the specific occurrence of the problem.

Example JSON payload:

{
    "type": "https://example.com/probs/out-of-credit",
    "title": "You do not have enough credit.",
    "detail": "Your current balance is 30, but that costs 50.",
    "instance": "/account/12345/transactions/abc"
}

Example XML payload:

<?xml version="1.0" encoding="UTF-8"?>
<problem xmlns="urn:ietf:rfc:7807">
    <type>https://example.com/probs/out-of-credit</type>
    <title>You do not have enough credit.</title>
    <detail>Your current balance is 30, but that costs 50.</detail>
    <instance>/account/12345/transactions/abc</instance>
</problem>

The response must include the appropriate Content-Type header ( application/problem+json or application/problem+xml) so clients can detect the format.

How to start using it

Although still a proposal, many frameworks already provide support: ASP.NET, Node.js (Express), Java (Spring Web MVC), Python (Django REST framework), Ruby (Rails, Sinatra), PHP (Symfony), as well as libraries for Rust, Go, Scala, Haskell, etc. Clients can signal support by sending Accept: application/problem+json (or +xml) in requests.

Recommendations for API providers

Return errors with the RFC 7807 content type whenever possible.

Extend existing error formats by adding the standard fields.

Detect the Accept header and negotiate the problem‑details format when supported.

Document the transition in your API specifications.

Recommendations for API consumers

Inspect error responses with the problem‑details content type and use the provided data to improve error reporting.

Include the appropriate Accept header to request standardized errors.

Encourage API owners to adopt the format for more consistent error handling.

Participate in the IETF "HTTP API Building Blocks" working group, join the mailing list, and help shape future API standards.