See equivalent in the Reactive stackspring-doc.cn

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 9457.spring-doc.cn

The following are the main abstractions for this support:spring-doc.cn

  • ProblemDetail — representation for an RFC 9457 problem detail; a simple container for both standard fields defined in the spec, and for non-standard ones.spring-doc.cn

  • 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.spring-doc.cn

  • ErrorResponseException — basic ErrorResponse implementation that others can use as a convenient base class.spring-doc.cn

  • ResponseEntityExceptionHandler — convenient base class for an @ControllerAdvice that handles all Spring MVC exceptions, and any ErrorResponseException, and renders an error response with a body.spring-doc.cn

Render

See equivalent in the Reactive stackspring-doc.cn

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:spring-doc.cn

  • The status property of ProblemDetail determines the HTTP status.spring-doc.cn

  • The instance property of ProblemDetail is set from the current URL path, if not already set.spring-doc.cn

  • 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.spring-doc.cn

To enable RFC 9457 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.spring-doc.cn

Non-Standard Fields

See equivalent in the Reactive stackspring-doc.cn

You can extend an RFC 9457 response with non-standard fields in one of two ways.spring-doc.cn

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.spring-doc.cn

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.spring-doc.cn

Customization and i18n

See equivalent in the Reactive stackspring-doc.cn

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.spring-doc.cn

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 MessageSource and updates the corresponding ProblemDetail fields accordingly.spring-doc.cn

The default strategy for message codes is as follows:spring-doc.cn

  • "type": problemDetail.type.[fully qualified exception class name]spring-doc.cn

  • "title": problemDetail.title.[fully qualified exception class name]spring-doc.cn

  • "detail": problemDetail.[fully qualified exception class name][suffix]spring-doc.cn

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:spring-doc.cn

Exception Message Code Message Code Arguments

AsyncRequestTimeoutExceptionspring-doc.cn

(default)spring-doc.cn

ConversionNotSupportedExceptionspring-doc.cn

(default)spring-doc.cn

{0} property name, {1} property valuespring-doc.cn

HandlerMethodValidationExceptionspring-doc.cn

(default)spring-doc.cn

{0} list all validation errors. Message codes and arguments for each error are also resolved via MessageSource.spring-doc.cn

HttpMediaTypeNotAcceptableExceptionspring-doc.cn

(default)spring-doc.cn

{0} list of supported media typesspring-doc.cn

HttpMediaTypeNotAcceptableExceptionspring-doc.cn

(default) + ".parseError"spring-doc.cn

HttpMediaTypeNotSupportedExceptionspring-doc.cn

(default)spring-doc.cn

{0} the media type that is not supported, {1} list of supported media typesspring-doc.cn

HttpMediaTypeNotSupportedExceptionspring-doc.cn

(default) + ".parseError"spring-doc.cn

HttpMessageNotReadableExceptionspring-doc.cn

(default)spring-doc.cn

HttpMessageNotWritableExceptionspring-doc.cn

(default)spring-doc.cn

HttpRequestMethodNotSupportedExceptionspring-doc.cn

(default)spring-doc.cn

{0} the current HTTP method, {1} the list of supported HTTP methodsspring-doc.cn

MethodArgumentNotValidExceptionspring-doc.cn

(default)spring-doc.cn

{0} the list of global errors, {1} the list of field errors. Message codes and arguments for each error are also resolved via MessageSource.spring-doc.cn

MissingRequestHeaderExceptionspring-doc.cn

(default)spring-doc.cn

{0} the header namespring-doc.cn

MissingServletRequestParameterExceptionspring-doc.cn

(default)spring-doc.cn

{0} the request parameter namespring-doc.cn

MissingMatrixVariableExceptionspring-doc.cn

(default)spring-doc.cn

{0} the matrix variable namespring-doc.cn

MissingPathVariableExceptionspring-doc.cn

(default)spring-doc.cn

{0} the path variable namespring-doc.cn

MissingRequestCookieExceptionspring-doc.cn

(default)spring-doc.cn

{0} the cookie namespring-doc.cn

MissingServletRequestPartExceptionspring-doc.cn

(default)spring-doc.cn

{0} the part namespring-doc.cn

NoHandlerFoundExceptionspring-doc.cn

(default)spring-doc.cn

NoResourceFoundExceptionspring-doc.cn

(default)spring-doc.cn

TypeMismatchExceptionspring-doc.cn

(default)spring-doc.cn

{0} property name, {1} property valuespring-doc.cn

UnsatisfiedServletRequestParameterExceptionspring-doc.cn

(default)spring-doc.cn

{0} the list of parameter conditionsspring-doc.cn
Unlike other exceptions, the message arguments for MethodArgumentValidException and HandlerMethodValidationException are baed on a list of MessageSourceResolvable errors that can also be customized through a MessageSource resource bundle. See Customizing Validation Errors for more details.
Exception Message Code Message Code Arguments

AsyncRequestTimeoutExceptionspring-doc.cn

(default)spring-doc.cn

ConversionNotSupportedExceptionspring-doc.cn

(default)spring-doc.cn

{0} property name, {1} property valuespring-doc.cn

HandlerMethodValidationExceptionspring-doc.cn

(default)spring-doc.cn

{0} list all validation errors. Message codes and arguments for each error are also resolved via MessageSource.spring-doc.cn

HttpMediaTypeNotAcceptableExceptionspring-doc.cn

(default)spring-doc.cn

{0} list of supported media typesspring-doc.cn

HttpMediaTypeNotAcceptableExceptionspring-doc.cn

(default) + ".parseError"spring-doc.cn

HttpMediaTypeNotSupportedExceptionspring-doc.cn

(default)spring-doc.cn

{0} the media type that is not supported, {1} list of supported media typesspring-doc.cn

HttpMediaTypeNotSupportedExceptionspring-doc.cn

(default) + ".parseError"spring-doc.cn

HttpMessageNotReadableExceptionspring-doc.cn

(default)spring-doc.cn

HttpMessageNotWritableExceptionspring-doc.cn

(default)spring-doc.cn

HttpRequestMethodNotSupportedExceptionspring-doc.cn

(default)spring-doc.cn

{0} the current HTTP method, {1} the list of supported HTTP methodsspring-doc.cn

MethodArgumentNotValidExceptionspring-doc.cn

(default)spring-doc.cn

{0} the list of global errors, {1} the list of field errors. Message codes and arguments for each error are also resolved via MessageSource.spring-doc.cn

MissingRequestHeaderExceptionspring-doc.cn

(default)spring-doc.cn

{0} the header namespring-doc.cn

MissingServletRequestParameterExceptionspring-doc.cn

(default)spring-doc.cn

{0} the request parameter namespring-doc.cn

MissingMatrixVariableExceptionspring-doc.cn

(default)spring-doc.cn

{0} the matrix variable namespring-doc.cn

MissingPathVariableExceptionspring-doc.cn

(default)spring-doc.cn

{0} the path variable namespring-doc.cn

MissingRequestCookieExceptionspring-doc.cn

(default)spring-doc.cn

{0} the cookie namespring-doc.cn

MissingServletRequestPartExceptionspring-doc.cn

(default)spring-doc.cn

{0} the part namespring-doc.cn

NoHandlerFoundExceptionspring-doc.cn

(default)spring-doc.cn

NoResourceFoundExceptionspring-doc.cn

(default)spring-doc.cn

TypeMismatchExceptionspring-doc.cn

(default)spring-doc.cn

{0} property name, {1} property valuespring-doc.cn

UnsatisfiedServletRequestParameterExceptionspring-doc.cn

(default)spring-doc.cn

{0} the list of parameter conditionsspring-doc.cn
Unlike other exceptions, the message arguments for MethodArgumentValidException and HandlerMethodValidationException are baed on a list of MessageSourceResolvable errors that can also be customized through a MessageSource resource bundle. See Customizing Validation Errors for more details.

Client Handling

See equivalent in the Reactive stackspring-doc.cn

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.spring-doc.cn