Skip to content

SYSTEM

RFC 7807 — Problem Details for HTTP API

Definition

RFC 7807 is an IETF standard (Nottingham & Wilde, 2016) that defines a canonical JSON shape for expressing errors in HTTP APIs. Rather than each service inventing its own error envelope, clients can rely on a small, discoverable set of well-known members:

Member Purpose
type URI identifying the problem type
title short, human-readable summary
status the original HTTP status code
detail human-readable explanation specific to this occurrence
instance URI identifying this specific occurrence

The media type is application/problem+json (or application/problem+xml).

Why it matters outside HTTP

Although the RFC is scoped to HTTP APIs, the vocabulary Problem Details has been adopted in other API substrates to name the same structural concern: an error as a first-class, typed payload, distinct from an exception or bug. Zalando's 2021 GraphQL errors post cites RFC 7807 explicitly as the source for calling schema-modelled errors Problems (not Errors):

"There is a well-defined concept in RFC 7807 - Problem details for HTTP API. So, we will call all our errors in Schema as Problems and, as it has always been, all other errors as errors."

(Source: )

This naming choice avoids colliding with GraphQL's reserved error keyword (response.errors) while borrowing an industry-standard term.

Design principles the RFC imports

  • Extensibility by design. The object may carry additional members beyond the standard ones, enabling structured per-domain extensions (e.g. invalidInputs: [...]).
  • URI-based problem type identity. The type field is a URI so two different services can share a problem-type identity (and so clients can dereference for documentation).
  • Distinction between problem type and occurrence. type identifies the kind of problem; instance identifies the specific occurrence. This matches how Zalando's Problem types work in GraphQL: the union member identifies the kind; fields on the member identify the occurrence.

In the wiki

Seen in

  • — cited by RFC number as the authority for the naming split.
Last updated · 542 distilled / 1,571 read