Skip to main content

Error Handling

azuma mimoto integrates the following error handling capabilities:

  • Technical errors, e.g. wrong client_ids, missing scopes, etc. are treated as technical integration errors and displayed directly as JSON formatted errors. Those need to resolved during integration.
  • Flow execution errors, e.g.: failing auth requests, failing token requests etc. are treated as technical runtime errors. Those can not be resolved during integration and need to be handled at runtime. azuma mimoto provides multiple integration scenarios (see below) that can be configured per Application to properly receive and process such errors.

Web flow​

Technical runtime errors​

Technical runtime errors can happen in Web flow during

(1) Authorization request​

Errors here could result from IDP not being available / usable (e.g. trust can not be established) or declining the auth request for some reasons.

(2) Internal code exchange (after authorization in authenticator app)​

Errors here could result from IDP not being available, token not being decryptable or verifiable.

(3) Token exchange​

Errors here could result from IDP wrong code / verifiers used.

Error handling modes​

The following error handling modes are available and can be configured on the relevant Application:

  • Default: In 'Default' mode the integrated error UI screen of azuma mimoto is displayed.
  • Redirect to Auth: Errors are redirected to the 'Redirect-URL' that was provided in the Auth-Request. Format: redirect-url?error=*error*
  • Redirect to Custom: Errors are redirected to the 'Custom-URL' that is configured for the Application Format: custom-url?error=*error*

App to App flow​

Technical runtime errors​

Technical runtime errors can happen in App to App during

(1) Authorization request (with selected/provided IDP)​

Errors here could result from IDP not being available / usable (e.g. trust can not be established) or declining the auth request for some reasons.

This scenario is not yet specified by gematik (see gematik FAQ: https://wiki.gematik.de/pages/viewpage.action?pageId=503588600, Point 5). But what can happen is that the error code is return in deep link call from authenticator, e.g. Verimi:

*redirect-deep-link*?error=access_denied....

Since this is not yet specified by gematik, we would advise showing a generic error message in case of such errors.

(3) Code exchange​

Errors here could result from given code not being correct, IDP not being available, token not being decryptable or verifiable.

(4) Token exchange​

Errors here could result from IDP wrong code / verifiers used.

Error handling modes​

For the App to App flow azuma mimoto usually returns errors in the default azuma mimoto JSON format. Only exception being if the authorization request is opened in the browser (with the IDP selection page of azuma mimoto).

Known error codes​

The following general error codes are supported (see https://www.rfc-editor.org/rfc/rfc6749#section-4.2.2.1)

  • access_denied
  • invalid_request
  • invalid_scope
  • server_error
  • temporarily_unavailable
  • unauthorized_client
  • unsupported_response_type