210 lines
7.8 KiB
Plaintext
210 lines
7.8 KiB
Plaintext
[[mvc-ann-rest-exceptions]]
|
|
= Error Responses
|
|
|
|
[.small]#xref:web/webflux/ann-rest-exceptions.adoc[See equivalent in the Reactive stack]#
|
|
|
|
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-site}/rfc9457[RFC 9457].
|
|
|
|
The following are the main abstractions for this support:
|
|
|
|
- `ProblemDetail` -- representation for an RFC 9457 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 9457; this allows exceptions to
|
|
encapsulate and expose the details of how they map to an HTTP response. All Spring MVC
|
|
exceptions implement this.
|
|
- `ErrorResponseException` -- basic `ErrorResponse` implementation that others
|
|
can use as a convenient base class.
|
|
- `ResponseEntityExceptionHandler` -- convenient base class for an
|
|
xref:web/webmvc/mvc-controller/ann-advice.adoc[@ControllerAdvice] that handles all Spring MVC exceptions,
|
|
and any `ErrorResponseException`, and renders an error response with a body.
|
|
|
|
|
|
|
|
[[mvc-ann-rest-exceptions-render]]
|
|
== Render
|
|
[.small]#xref:web/webflux/ann-rest-exceptions.adoc#webflux-ann-rest-exceptions-render[See equivalent in the Reactive stack]#
|
|
|
|
You can return `ProblemDetail` or `ErrorResponse` from any `@ExceptionHandler` or from
|
|
any `@RequestMapping` method to render an RFC 9457 response. This is processed as follows:
|
|
|
|
- The `status` property of `ProblemDetail` determines the HTTP status.
|
|
- The `instance` property of `ProblemDetail` 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 a `ProblemDetail`,
|
|
and also falls back on it if no compatible media type is found.
|
|
|
|
To enable RFC 9457 responses for Spring WebFlux exceptions and for any
|
|
`ErrorResponseException`, extend `ResponseEntityExceptionHandler` and declare it as an
|
|
xref:web/webmvc/mvc-controller/ann-advice.adoc[@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`.
|
|
|
|
You can register `ErrorResponse` interceptors through the
|
|
xref:web/webmvc/mvc-config.adoc[MVC Config] with a `WebMvcConfigurer`. Use that to intercept
|
|
any RFC 9457 response and take some action.
|
|
|
|
|
|
|
|
[[mvc-ann-rest-exceptions-non-standard]]
|
|
== Non-Standard Fields
|
|
[.small]#xref:web/webflux/ann-rest-exceptions.adoc#webflux-ann-rest-exceptions-non-standard[See equivalent in the Reactive stack]#
|
|
|
|
You can extend an RFC 9457 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, for example, from an
|
|
`@ControllerAdvice` such as `ResponseEntityExceptionHandler` that re-creates the
|
|
`ProblemDetail` of an exception into a subclass with the additional non-standard fields.
|
|
|
|
|
|
|
|
[[mvc-ann-rest-exceptions-i18n]]
|
|
== Customization and i18n
|
|
[.small]#xref:web/webflux/ann-rest-exceptions.adoc#webflux-ann-rest-exceptions-i18n[See equivalent in the Reactive stack]#
|
|
|
|
It is a common requirement to customize and internationalize error response details.
|
|
It is also good practice to customize the problem details for Spring MVC exceptions
|
|
to avoid revealing implementation details. This section describes the support for that.
|
|
|
|
An `ErrorResponse` exposes message codes for "type", "title", and "detail", as well as
|
|
message code arguments for the "detail" field. `ResponseEntityExceptionHandler` resolves
|
|
these through a xref:core/beans/context-introduction.adoc#context-functionality-messagesource[MessageSource]
|
|
and updates the corresponding `ProblemDetail` fields accordingly.
|
|
|
|
The default strategy for message codes is as follows:
|
|
|
|
* "type": `problemDetail.type.[fully qualified exception class name]`
|
|
* "title": `problemDetail.title.[fully qualified exception class name]`
|
|
* "detail": `problemDetail.[fully qualified exception class name][suffix]`
|
|
|
|
An `ErrorResponse` may expose more than one message code, typically adding a suffix
|
|
to the default message code. The table below lists message codes, and arguments for
|
|
Spring MVC exceptions:
|
|
|
|
[[mvc-ann-rest-exceptions-codes]]
|
|
[cols="1,1,2", options="header"]
|
|
|===
|
|
| Exception | Message Code | Message Code Arguments
|
|
|
|
| `AsyncRequestTimeoutException`
|
|
| (default)
|
|
|
|
|
|
|
| `ConversionNotSupportedException`
|
|
| (default)
|
|
| `+{0}+` property name, `+{1}+` property value
|
|
|
|
| `HandlerMethodValidationException`
|
|
| (default)
|
|
| `+{0}+` list all validation errors.
|
|
Message codes and arguments for each error are also resolved via `MessageSource`.
|
|
|
|
| `HttpMediaTypeNotAcceptableException`
|
|
| (default)
|
|
| `+{0}+` list of supported media types
|
|
|
|
| `HttpMediaTypeNotAcceptableException`
|
|
| (default) + ".parseError"
|
|
|
|
|
|
|
| `HttpMediaTypeNotSupportedException`
|
|
| (default)
|
|
| `+{0}+` the media type that is not supported, `+{1}+` list of supported media types
|
|
|
|
| `HttpMediaTypeNotSupportedException`
|
|
| (default) + ".parseError"
|
|
|
|
|
|
|
| `HttpMessageNotReadableException`
|
|
| (default)
|
|
|
|
|
|
|
| `HttpMessageNotWritableException`
|
|
| (default)
|
|
|
|
|
|
|
| `HttpRequestMethodNotSupportedException`
|
|
| (default)
|
|
| `+{0}+` the current HTTP method, `+{1}+` the list of supported HTTP methods
|
|
|
|
| `MethodArgumentNotValidException`
|
|
| (default)
|
|
| `+{0}+` the list of global errors, `+{1}+` the list of field errors.
|
|
Message codes and arguments for each error are also resolved via `MessageSource`.
|
|
|
|
| `MissingRequestHeaderException`
|
|
| (default)
|
|
| `+{0}+` the header name
|
|
|
|
| `MissingServletRequestParameterException`
|
|
| (default)
|
|
| `+{0}+` the request parameter name
|
|
|
|
| `MissingMatrixVariableException`
|
|
| (default)
|
|
| `+{0}+` the matrix variable name
|
|
|
|
| `MissingPathVariableException`
|
|
| (default)
|
|
| `+{0}+` the path variable name
|
|
|
|
| `MissingRequestCookieException`
|
|
| (default)
|
|
| `+{0}+` the cookie name
|
|
|
|
| `MissingServletRequestPartException`
|
|
| (default)
|
|
| `+{0}+` the part name
|
|
|
|
| `NoHandlerFoundException`
|
|
| (default)
|
|
|
|
|
|
|
| `NoResourceFoundException`
|
|
| (default)
|
|
|
|
|
|
|
| `TypeMismatchException`
|
|
| (default)
|
|
| `+{0}+` property name, `+{1}+` property value
|
|
|
|
| `UnsatisfiedServletRequestParameterException`
|
|
| (default)
|
|
| `+{0}+` the list of parameter conditions
|
|
|
|
|===
|
|
|
|
NOTE: Unlike other exceptions, the message arguments for
|
|
`MethodArgumentValidException` and `HandlerMethodValidationException` are based on a list of
|
|
`MessageSourceResolvable` errors that can also be customized through a
|
|
xref:core/beans/context-introduction.adoc#context-functionality-messagesource[MessageSource]
|
|
resource bundle. See
|
|
xref:core/validation/beanvalidation.adoc#validation-beanvalidation-spring-method-i18n[Customizing Validation Errors]
|
|
for more details.
|
|
|
|
|
|
|
|
[[mvc-ann-rest-exceptions-client]]
|
|
== Client Handling
|
|
[.small]#xref:web/webflux/ann-rest-exceptions.adoc#webflux-ann-rest-exceptions-client[See equivalent in the Reactive stack]#
|
|
|
|
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`.
|
|
|
|
|
|
|