Problem Details

API Design

Meaning

Problem Details is a standardized format (RFC 7807, updated by RFC 9457) for HTTP error responses that conveys machine-readable error information using the application/problem+json or application/problem+xml media type. It addresses the pain point of inconsistent, opaque error payloads that force API clients to parse free-form strings or guess at error semantics. Developers reach for it whenever designing or consuming REST APIs that need structured, interoperable error reporting.

Primary Function

API error response standardization

Communicative Purpose

Ensures HTTP error responses carry structured, machine-readable diagnostics that any compliant client can parse without per-API custom logic.

Pattern

return response with Content-Type: application/problem+json and body { type, title, status, detail, instance }

Função primária

API error response standardization

Propósito comunicativo

Ensures HTTP error responses carry structured, machine-readable diagnostics that any compliant client can parse without per-API custom logic.

Situações de gatilho

REST API design: returning 4xx/5xx errors with structured detail beyond a bare status code API client integration: parsing error responses to surface user-facing messages or trigger retries Microservices: propagating error context across service boundaries in a uniform format

Contextos

RESTful HTTP APIs, microservices, OpenAPI specifications, ASP.NET Core, Spring Boot, FastAPI, Express middleware

Padrão

return response with Content-Type: application/problem+json and body { type, title, status, detail, instance }

Colocados típicos

application/problem+json media type
HTTP 4xx/5xx status codes
ProblemDetails class
exception handler middleware
RFC 7807
RFC 9457

Substituições comuns

Plain JSON error envelope { error: { code
message } }: simpler but non-standard and harder for generic tooling to consume HTML error pages: human-readable but not machine-parseable Custom error schema per service: flexible but breaks client interoperability

Erros comuns

Omitting the type URI: clients cannot programmatically distinguish problem categories, forcing string matching on title Returning application/json instead of application/problem+json: breaks content negotiation and signals non-compliance to generic clients Including sensitive stack traces in detail: leaks internal implementation details to attackers Setting status in the body to a value different from the HTTP status code: creates contradictory signals that confuse retry logic Forgetting to set instance: clients cannot correlate the error to a specific request in logs

Similar / contraste

JSON:API error objects: similar structured errors but scoped to JSON:API resources Google API error format: uses { error: { code, message, errors } } envelope, not a top-level problem document GraphQL error format: returns errors[] array alongside data, not a dedicated error response

Interferências

Coming from SOAP/WSDL: may expect a single fault element with code/string fields — Problem Details uses five top-level members and a dedicated media type Coming from gRPC: may expect status codes in a trailer and rich Status proto — Problem Details is HTTP-native and JSON-shaped, not protobuf Coming from plain Express.js: may default to res.json({ error: msg }) — must explicitly set Content-Type to application/problem+json to be compliant

Família do chunk

HTTP status codes
application/problem+json media type
RFC 7807
RFC 9457
API error envelopes
ProblemDetails .NET class

Nuance

Do not use for successful 2xx responses or for non-error informational payloads — the format is reserved for problem conditions. The type field should be a dereferenceable URI (often a URL to documentation) but clients must not fail when it is unresolvable. RFC 9457 adds extension members freely, so custom fields coexist with the five standard members without breaking compliance.

Efeito pragmático

Adopting Problem Details lets API consumers write one error-handling path that works across every compliant endpoint, reducing client-side branching and enabling generic tooling like API gateways and error trackers to surface meaningful diagnostics without per-service customization.

Dica de memória

Problem Details is like a standardized error receipt: every HTTP error carries the same five labeled fields so any client can read it without learning a new dialect.

Upgrade path

RFC 9457 extensions: adding custom members for domain-specific diagnostics while preserving the five standard fields

Frequência: MediumFormulaicidade: Semi-fixedPrioridade de aquisição: Recognition firstPrioridade de output: BothTag de espaçamento: Medium-term

Examples

from fastapi import FastAPI from fastapi.responses import JSONResponse app = FastAPI() @app.get("/accounts/{account_id}") def get_account(account_id: int): account = lookup_account(account_id) if account is None: return JSONResponse( status_code=404, media_type="application/problem+json", content={ "type": "https://example.com/probs/account-not-found", "title": "Account not found", "status": 404, "detail": f"No account exists with id {account_id}.", "instance": f"/accounts/{account_id}", }, ) return account

import org.springframework.http.MediaType; import org.springframework.http.ResponseEntity; import org.springframework.web.bind.annotation.ExceptionHandler; import org.springframework.web.bind.annotation.RestControllerAdvice; import jakarta.servlet.http.HttpServletRequest; import java.util.LinkedHashMap; import java.util.Map; @RestControllerAdvice public class ProblemDetailsHandler { @ExceptionHandler(OrderNotFoundException.class) public ResponseEntity<Map<String, Object>> handleNotFound( OrderNotFoundException ex, HttpServletRequest request) { Map<String, Object> problem = new LinkedHashMap<>(); problem.put("type", "https://example.com/probs/order-not-found"); problem.put("title", "Order not found"); problem.put("status", 404); problem.put("detail", ex.getMessage()); problem.put("instance", request.getRequestURI()); return ResponseEntity.status(404) .contentType(MediaType.valueOf("application/problem+json")) .body(problem); } }