API Design - Error Handling should include RFC6749 exception

[laughingbiscuit]

Problem description

The API Design Guidelines discuss the standardized error format.

{
   "status": 400,
   "code": "INVALID_ARGUMENT",
   "message": "A human readable description of what the event represent"
}

This makes sense for most APIs, except existing OAuth APIs such as when obtaining client_credentials access token. There are already errors defined for this in the format here:

{
  "error":"xxx",
  "error_description": "xxx",
  "error_uri": "xxx"
}

Expected action

Documentation should indicate which format takes priority.

[eric-murray]

The API design guidelines only apply to the service APIs. The standards and profiles that apply to the authentication flow itself are being discussed within the Identity & Consent working group. The already standardised error response will apply unless changes are agreed by that working group.

[rartych]

@jpengar Could you get some insights/views from Identity & Consent subproject how to resolve this issue? More specific problem is also presented also in #128.

[AxelNennker]

@rartych As per your request I commented on the original issue https://github.com/camaraproject/Commonalities/issues/128#issuecomment-1942012539

Which is about what OIDC and OAuth2 define as error responses for their endpoints.

The document https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#6-error-responses talks about resource server responses which are not standardized by OIDC nor OAuth2. So, Camara can recommend/define what ever Camara wants without violating OIDF or IETF standards.

I think there is no contradiction here and the issue can be closed, but maybe I am missing the point.

[jpengar]

I agree with Axel. On the one hand we have the AuthZ/AuthN process to get an access_token to access CAMARA Service APIs. The authorization flows agreed in CAMARA follow the OpenID connect/OAuth standards. So the error format will be the one defined by those standards for the Authorize Request and the Token Request. On the other hand, we have CAMARA NBI interface to consume Service APIs, i.e. API client uses obtained access_token to consume the target CAMARA API for which the access_token was obtained. The API design guidelines, and especially in this case the defined error format, only apply to the invocation of service APIs.