Problem Details
A standard JSON shape for HTTP error responses, defined in RFC 9457, with members such as type, title, status, detail and instance.
In more detail
It is defined by RFC 9457 (July 2023), which obsoletes the original RFC 7807; responses written for 7807 are still valid. Its media type is application/problem+json. Type is a stable identifier clients can branch on (about:blank when nothing more specific applies), title is a short human label, status repeats the HTTP status, detail explains this occurrence safely, and instance can identify the occurrence. Extra members are allowed but must be documented and must not clash with the standard names.
Examples
{"type":"about:blank","title":"Not Found","status":404,"detail":"No task 999"}{ "type": "https://api.acme.com/errors/http-404", "title": "Not Found", "status": 404, "detail": "User account missing", "instance": "/users/u10" }Spring: ProblemDetail.forStatusAndDetail(404, error.getMessage())Related terms
- HTTP status code — The three-digit number at the start of a response, such as 200 or 404, that says how the server handled the request.
- leaky error — An error response that reveals private details such as a stack trace, a database query, a secret or internal names.
- media type — A standard label for a data format, written type/subtype, such as application/json or text/event-stream.
- exception handler middleware — ASP.NET Core middleware, added with app.UseExceptionHandler(), that catches unhandled exceptions from later components and returns a safe error response.
- field error — A validation failure tied to one input field, reported with the field name and a message such as "must not be blank".
- trace ID — An identifier shared by every span and log line belonging to one request, so they can be found together.
- error envelope — A fixed wrapper shape for every error response, so clients can read any error the same way.
- Content-Type — The header that states what format a message body is in, such as application/json.
- correlation ID — A unique value attached to one request and passed along everywhere it goes, so its logs and traces can be found together.
- controller advice — A Spring class, marked @RestControllerAdvice, whose exception handlers apply across all controllers, giving one failure policy for every route.
- RFC — A numbered document published by the RFC Editor, many of which are the official standards for internet protocols such as HTTP.
- OpenAPI — A standard, language-neutral format for describing an HTTP API: its paths, operations, parameters, request and response schemas, errors and security.
Taught in
- What An API Is, And The Alternatives — Modern API Architecture: REST, GraphQL & gRPC
- Filtering And Searching — Modern API Architecture: REST, GraphQL & gRPC
- Problem Details: RFC 9457 — Modern API Architecture: REST, GraphQL & gRPC
- Handling PII And Data Privacy — Modern API Architecture: REST, GraphQL & gRPC
- Building Routes with Controllers — Modern .NET Core, C# & Enterprise Microservices
- Model Validation and FluentValidation — Modern .NET Core, C# & Enterprise Microservices
- Global Exception Handling and Problem Details — Modern .NET Core, C# & Enterprise Microservices
- Type-Safe RPC Architectures: tRPC & Procedures — Production Full-Stack Engineering
- Resilient Error Handling: Problem Details & Envelopes — Production Full-Stack Engineering
- The Cost Of Checked Exceptions — Modern Java: Virtual Threads & High-Throughput Services
- Async With CompletableFuture — Modern Java: Virtual Threads & High-Throughput Services
- Validation — Modern Java: Virtual Threads & High-Throughput Services
- Exception Handling To Problem Details — Modern Java: Virtual Threads & High-Throughput Services
- Tying It All Together — Modern Java: Virtual Threads & High-Throughput Services
- The Spine Artifact: Generating Typed Models From OpenAPI — Production TypeScript