ReviseAlgo Logo

Validation & Exception Handling

RFC 7807 Problem Details — Standardized Error Responses

Implementing standardized REST error payload specifications in Spring Boot 3.

Last Updated: June 14, 2026 • 10 min read

Introduction

Prior to Spring Boot 3, there was no standard response payload structure for REST API errors. Teams had to write custom error class representations, leading to inconsistent clients. Spring Boot 3 natively supports **RFC 7807 Problem Details for HTTP APIs**, an IETF specification defining standard JSON formats to describe errors.

Why It Matters

Standardizing API errors reduces friction for API consumers. Clients (front-ends, SDKs, external integrators) can write a single, standardized client-side handler class that parses all API error responses predictably. This standard format includes elements like unique URI references for error descriptions, localized summaries, and dynamic parameter fields.

Real-World Analogy

Think of RFC 7807 like standardized shipping return labels. Before the standard, every shop had its own return form format (some asked for transaction ID first, some asked for names, some had custom codes). When shops transitioned to the standard return format (RFC 7807), logistics companies could scan and process returns automatically and uniformly, no matter the retailer.

How It Works

An RFC 7807 JSON error body contains standard fields:

  • type: A URI reference identifying the problem type (defaults to about:blank).
  • title: A short, human-readable summary of the problem type.
  • status: The HTTP status code (e.g., 400, 404).
  • detail: A detailed human-readable explanation of this specific occurrence.
  • instance: A URI reference identifying the specific request path where the error occurred.

Spring Boot 3 introduces org.springframework.http.ProblemDetail, which encapsulates these fields, and allows custom extension fields (like validation field lists) via the setProperty(key, value) mapping method.

Practical Example

To enable RFC 7807 globally in Spring Boot 3, you set the configuration property:

Here is how to return RFC 7807 errors from a custom global exception handler using Spring's ProblemDetail API:

Quick Quiz

Q1: Which Spring property enables the default Problem Details handler structure automatically in controllers?

A) spring.error.rfc7807=true

B) spring.mvc.problemdetails.enabled=true

C) spring.web.errors.standardize=true

D) spring.problem-detail.on=true

Answer: B — Enabling spring.mvc.problemdetails.enabled triggers Spring Boot's internal handlers to return ProblemDetail representation.

Q2: How do you append custom custom fields (like errors or timestamp) to a ProblemDetail instance?

A) By inheriting class fields from ProblemDetail

B) Using the setProperty(key, value) method on the ProblemDetail object

C) Pass them as a Map into the constructor

D) It is impossible; RFC 7807 has a strictly closed schema

Answer: B — ProblemDetail exposes setProperty(String, Object) to extend JSON keys.

Scenario-Based Challenge

Production Scenario:

You have enabled spring.mvc.problemdetails.enabled=true. Your frontend developers are complaining that when they send invalid requests, they receive standard JSON error documents, but the HTTP Content-Type header is application/problem+json instead of the standard application/json. What should you tell them?

View Solution

This is correct behavior according to the RFC 7807 specification. Problem Details payloads must be served using the application/problem+json Media Type (and application/problem+xml for XML-based responses). Frontend developers should modify their client libraries or middleware to check for or allow application/problem+json headers alongside standard JSON, as they are fully compatible JSON structures.

Interview Questions

1. What is the value of the "instance" field in an RFC 7807 Problem Detail response?

The instance field contains a relative or absolute URI representing the specific API endpoint resource where the error occurrence occurred (e.g. /api/transfers/87241), helping operators correlate client tickets with API request access logs.

2. What helper class does Spring Boot 3 provide that you can extend to gain default RFC 7807 handling for Spring's standard exception mappings?

You can extend ResponseEntityExceptionHandler inside your @RestControllerAdvice class. It provides default handling for standard MVC exceptions (like HttpRequestMethodNotSupportedException or HttpMediaTypeNotSupportedException) and formats them automatically as ProblemDetail objects.

Production Considerations

Use a standard host URI for the type field that serves documentation describing the error and how a developer can fix it. Avoid hardcoding random URIs; set up error code pages on your developer documentation site to match the mapped types.