Error Responses
A common requirement for REST services is to include details in the body of error responses. The Spring Framework supports the "Problem Details for HTTP APIs" specification, RFC 7807.
The following are the main abstractions for this support:
-
ProblemDetail
— representation for an RFC 7807 problem detail; a simple container for both standard fields defined in the spec, and for non-standard ones. -
ErrorResponse
— contract to expose HTTP error response details including HTTP status, response headers, and a body in the format of RFC 7807; this allows exceptions to encapsulate and expose the details of how they map to an HTTP response. All Spring MVC exceptions implement this. -
ErrorResponseException
— basicErrorResponse
implementation that others can use as a convenient base class. -
ResponseEntityExceptionHandler
— convenient base class for an @ControllerAdvice that handles all Spring MVC exceptions, and anyErrorResponseException
, and renders an error response with a body.
Render
You can return ProblemDetail
or ErrorResponse
from any @ExceptionHandler
or from
any @RequestMapping
method to render an RFC 7807 response. This is processed as follows:
-
The
status
property ofProblemDetail
determines the HTTP status. -
The
instance
property ofProblemDetail
is set from the current URL path, if not already set. -
For content negotiation, the Jackson
HttpMessageConverter
prefers "application/problem+json" over "application/json" when rendering aProblemDetail
, and also falls back on it if no compatible media type is found.
To enable RFC 7807 responses for Spring WebFlux exceptions and for any
ErrorResponseException
, extend ResponseEntityExceptionHandler
and declare it as an
@ControllerAdvice in Spring configuration. The handler
has an @ExceptionHandler
method that handles any ErrorResponse
exception, which
includes all built-in web exceptions. You can add more exception handling methods, and
use a protected method to map any exception to a ProblemDetail
.
Non-Standard Fields
You can extend an RFC 7807 response with non-standard fields in one of two ways.
One, insert into the "properties" Map
of ProblemDetail
. When using the Jackson
library, the Spring Framework registers ProblemDetailJacksonMixin
that ensures this
"properties" Map
is unwrapped and rendered as top level JSON properties in the
response, and likewise any unknown property during deserialization is inserted into
this Map
.
You can also extend ProblemDetail
to add dedicated non-standard properties.
The copy constructor in ProblemDetail
allows a subclass to make it easy to be created
from an existing ProblemDetail
. This could be done centrally, e.g. from an
@ControllerAdvice
such as ResponseEntityExceptionHandler
that re-creates the
ProblemDetail
of an exception into a subclass with the additional non-standard fields.
Internationalization
It is a common requirement to internationalize error response details, and good practice to customize the problem details for Spring MVC exceptions. This is supported as follows:
-
Each
ErrorResponse
exposes a message code and arguments to resolve the "detail" field through a MessageSource. The actual message code value is parameterized with placeholders, e.g."HTTP method {0} not supported"
to be expanded from the arguments. -
Each
ErrorResponse
also exposes a message code to resolve the "title" field. -
ResponseEntityExceptionHandler
uses the message code and arguments to resolve the "detail" and the "title" fields.
By default, the message code for the "detail" field is "problemDetail." + the fully qualified exception class name. Some exceptions may expose additional message codes in which case a suffix is added to the default message code. The table below lists message arguments and codes for Spring MVC exceptions:
Exception | Message Code | Message Code Arguments |
---|---|---|
|
(default) |
|
|
(default) |
|
|
(default) |
|
|
(default) + ".parseError" |
|
|
(default) |
|
|
(default) + ".parseError" |
|
|
(default) |
|
|
(default) |
|
|
(default) |
|
|
(default) |
|
|
(default) |
|
|
(default) |
|
|
(default) |
|
|
(default) |
|
|
(default) |
|
|
(default) |
|
|
(default) |
|
|
(default) |
|
|
(default) |
|
By default, the message code for the "title" field is "problemDetail.title." + the fully qualified exception class name.
Client Handling
A client application can catch WebClientResponseException
, when using the WebClient
,
or RestClientResponseException
when using the RestTemplate
, and use their
getResponseBodyAs
methods to decode the error response body to any target type such as
ProblemDetail
, or a subclass of ProblemDetail
.