title: OAuth 2.0 resource server custom error format
body: <p>The OAuth 2.0 <a href="https://www.rfc-editor.org/rfc/rfc6749" rel="nofollow noreferrer">specification</a> is very clear on the errors returned by the authorization server in <a href="https://www.rfc-editor.org/rfc/rfc6749#section-5.2" rel="nofollow noreferrer">Section 5.2. Error Response</a> :</p>
  <blockquote>
  <ul>
  <li><strong>error</strong> : REQUIRED.</li>
  </ul>
  </blockquote>
  <ul>
  <li><strong>error_description</strong> : OPTIONAL</li>
  <li><strong>error_uri</strong> : OPTIONAL</li>
  </ul>
  <blockquote>
  <p>[...]</p>
  <p>The parameters are included in the entity-body of the HTTP response
  using the &quot;application/json&quot; media type as defined by [RFC4627].</p>
  </blockquote>
  <p>A sample HTTP response is even provided :</p>
  <pre><code> HTTP/1.1 400 Bad Request
   Content-Type: application/json;charset=UTF-8
   Cache-Control: no-store
   Pragma: no-cache
  
   {
     &quot;error&quot;:&quot;invalid_request&quot;
   }
  </code></pre>
  <p>When it comes to the resource server (the protected HTTP resources), the RFC is vague about this part in <a href="https://www.rfc-editor.org/rfc/rfc6749#section-7.2" rel="nofollow noreferrer">Section 7.2</a> :</p>
  <blockquote>
  <p>If a resource access request fails, the resource server SHOULD inform
  the client of the error.<br />
  While the specifics of such error responses
  are beyond the scope of this specification, this document establishes
  a common registry in Section...</p>
  </blockquote>
  <p>One may already have its custom error response &quot;data structure&quot; in place.
  Implementations like spring-security-oauth2 use the same error format for the authorization server and resource server by default.</p>
  <p>This default behavior would lead API clients to process two different data structures for authorization errors and business errors, which is highly inconvenient.</p>
  <p>On the other hand, I find it really weird to mold an HTTP API's errors based on the authorization framework : especially when we use multiple types of authorization/authentication for the same resources.</p>
  <p>At this point I find it more appealing to have the same user-defined error structure for all resource server errors, including OAuth-related authorization errors like &quot;invalid_token&quot;.</p>
  <p>ex :</p>
  <pre><code>{
    &quot;error&quot;: {
      &quot;code&quot;:&quot;1001&quot;
      &quot;type&quot;:&quot;invalid_token&quot;
      &quot;message&quot;:&quot;Expired access token&quot;
    }
    ...
  }
  </code></pre>
  <p><em><strong>Question :</strong></em> is it a &quot;bad&quot;/uncommon practice to define our own error response format for the resource server ? Any elements I may forget to consider ?</p>
  <p>The idea is to be as user-friendly as possible.</p>