Defining error format is important part of REST API design.

Spring-Boot and Spring Security provide pretty nice error handling for RESTful APIs out of the box. Although it has to be documented, especially when contract-first approach to API design is used.

It is good idea to follow some common format for error responses. But OAuth2 specification and Spring Boot format may not satisfy those requirements.

By default, Spring Boot returns errors messages like this:

    "timestamp": "2018-06-27T16:36:47.390+0000",
    "status": 404,
    "error": "Not Found",
    "message": "Not Found",
    "path": "/service/v1/user/1d28c5cb-54fe-4f75-9af0-37fd611d0ece"

The format of this response is defined by the DefaultErrorAttributes class.

It make sense to adopt your «custom» error message format to this one just to save make your life easier.

There are few possible ways to define your custom error response:

  • You may use @ControllerAdvice to create a single global error handling component:

    public ErrorResponse handleServiceException(HttpServletRequest req, HttpServletResponse response, ServiceException e) 
        ErrorResponse error = new ErrorResponse();
        //Set custom non standard http status code
        return error;
  • You may hide exception from DefaultErrorAttributes by clearing a request attribute:

    void handleIllegalArgumentException(HttpServletRequest request, HttpServletResponse response) throws IOException {
        request.setAttribute(DefaultErrorAttributes.class.getName() + ".ERROR", null);
        response.sendError(HttpStatus.BAD_REQUEST.value(), "custom message");
  • You may also provide your own ErrorAttributes implementation to get full control: on error payload:

    public ErrorAttributes errorAttributes() {
        return new DefaultErrorAttributes() {
            public Map<String, Object> getErrorAttributes(
                    RequestAttributes requestAttributes,
                    boolean includeStackTrace) {
                Map<String, Object> errorAttributes = super.getErrorAttributes(requestAttributes, includeStackTrace);
                Object errorMessage = requestAttributes.getAttribute(RequestDispatcher.ERROR_MESSAGE, RequestAttributes.SCOPE_REQUEST);
                if (errorMessage != null) {
                    errorAttributes.put("message",  errorMessage);
                return errorAttributes;

This may work for you…Unless you’re using Spring-Security-OAuth2.


Spring-Security-OAuth2 implements resource server specification according to OAuth 2.0 (RFC6749) section 7.2

If a resource access request fails, the resource server SHOULD inform the client of the error. While the specifics of such error responses are beyond the scope of this specification, this document establishes a common registry in Section 11.4 for error values to be shared among OAuth token authentication schemes.

New authentication schemes designed primarily for OAuth token authentication SHOULD define a mechanism for providing an error status code to the client, in which the error values allowed are registered in the error registry established by this specification.

Such schemes MAY limit the set of valid error codes to a subset of the registered values. If the error code is returned using a named parameter, the parameter name SHOULD be «error».

Other schemes capable of being used for OAuth token authentication, but not primarily designed for that purpose, MAY bind their error values to the registry in the same manner.

New authentication schemes MAY choose to also specify the use of the «error_description» and «error_uri» parameters to return error information in a manner parallel to their usage in this specification.

So error response will look like:

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache


Fragment of OpenAPI 3 definition will look like this (openapi.yaml):


      description: Authorization required
        $ref: '#/definitions/OAuth2ErrorResponse'
      description: Access is denied
        $ref: '#/definitions/OAuth2ErrorResponse'

      description: |-
        Spring-Security-OAuth2 implements resource server specification according to
        [RFC6749 section 7.2](
          description: |-
            A single ASCII (USASCII) error code from the list
          type: string
           - invalid_request
           - invalid_client
           - invalid_grant
           - unauthorized_client
           - unsupported_grant_type
           - invalid_scope
           - insufficient_scope
           - invalid_token
           - redirect_uri_mismatch
           - unsupported_response_type
           - access_denied
          description: |-
            Human-readable ASCII (USASCII) text providing
            additional information, used to assist the client developer in
            understanding the error that occurred.
          type: string
          pattern: "[\x20-\x7E|\x23-\x5B|\x5D-\x7E]+"
          description: |-
            A URI identifying a human-readable web page with
            information about the error, used to provide the client
            developer with additional information about the error.
          type: string
          pattern: "[\x20-\x7E|\x23-\x5B|\x5D-\x7E]+"
        description: OAuth 2.0 (RFC6749) Section 7.2

If you’re using swagger-codegen-plugin, it make sense to define import mapping for this type (pom.xml):


If you want to describe common error response in swagger, in some cases, you can not differentiate error thrown by spring-security-oauth2 from errors thrown by controller.

E.g. for access_denied case: the reason could be declarative security (@PreAuthorize), custom business logic in your service (thus security exception is thrown by your code) or oauth2-related exception which is thrown at the higher level.

This is because spring-security-oauth2 has a different class for error response: OAuth2Exception.

But you may still tune error response by adding some additional fields. You may define some common set of fields that are present in all error responses, thus define a consistent contract for API consumers.

Customizing Error Response for OAuth2

The class DefaultWebResponseExceptionTranslator translates thrown exceptions (e.g. InsufficientAuthenticationException) to OAuth2Exception.

You may add some additional information to error response by customizing OAuth2Exception.additionalFields. You have to use your own WebResponseExceptionTranslator instead of default one.

In case of resource server you may inject your ExceptionTranslator (OAuth2ResourceServerConfiguration.kt):

import org.springframework.context.annotation.Configuration

class OAuth2ResourceServerConfiguration(
    private val exceptionTranslator: CustomWebResponseExceptionTranslator
) : ResourceServerConfigurerAdapter() {

    override fun configure(resources: ResourceServerSecurityConfigurer) {
        val authenticationEntryPoint = OAuth2AuthenticationEntryPoint()

        val accessDeniedHandler = OAuth2AccessDeniedHandler()

If you’re hacking Authorization server - then solution is:

protected static class AuthorizationServerConfig extends AuthorizationServerConfigurerAdapter {
    CustomWebResponseExceptionTranslator exceptionTranslator;
    public void configure(AuthorizationServerEndpointsConfigurer endpoints) throws Exception {

…and then hack a OAuth2Exception before marshalling (CustomWebResponseExceptionTranslator.kt):

import org.springframework.http.ResponseEntity
import org.springframework.stereotype.Component
import java.lang.Exception
import java.time.Clock
import java.time.ZoneId
import java.time.format.DateTimeFormatter

class CustomWebResponseExceptionTranslator(private val clock: Clock) : DefaultWebResponseExceptionTranslator() {

    private val dateTimeFormat = DateTimeFormatter.ISO_OFFSET_DATE_TIME.withZone(ZoneId.of("UTC"))

    override fun translate(e: Exception): ResponseEntity<OAuth2Exception> {
        return with(super.translate(e)) {
            body?.let {
                it.addAdditionalInformation("timestamp", dateTimeFormat.format(clock.instant()))
                it.addAdditionalInformation("status", it.httpErrorCode.toString())
                it.addAdditionalInformation("message", it.message)
                it.addAdditionalInformation("code", it.oAuth2ErrorCode.toUpperCase())

Error response will now have an extra fields:

    "error": "unauthorized",
    "error_description": "Full authentication is required to access this resource",
    "code": "UNAUTHORIZED",
    "message": "Full authentication is required to access this resource",
    "status": "401",
    "timestamp": "2018-06-28T23:55:28.86Z"

Now you may describe a generic error message in your swagger file with required fields having both "error" field (which is required by OAuth 2.0 specification) and some other fields, e.g. "timestamp", "code", and "message".