1. Introduction

This page provides guidance on error handling and error scenarios for LFIs who are integrating with the Headless Authorization Server (“Heimdall”) API at the API Hub.

This page must be read in conjunction with the Authorization Server OpenAPI description page.

2. Context

The Ozone Headless Authorization Server (“Heimdall”) provides a two primary features for LFIs operating in the Open Finance Framework:

Provides validation of Authorization Request parameters, including Client and JWT-Secured Authorization Request (JAR) parameters.
Allow the status of a given User going through authentication and authorization to be tracked and the appropriate redirect URI to be returned.

The API is typically invoked before and after the User has authenticated at the LFI and authorised the consent. The sequence diagram below provides an excerpt of the API Hub Sequence Diagrams that describe the end-to-end flow, focusing on the Heimdall API.

Headless Authorization Server API

3. Success Response

When validation of the redirection is successful the properties of Pushed Authorization Request and the TPP who sent the Pushed Authorization Request are available in the response. The values returned in the success response, indicated by the a 200 HTTP status code, include the login_hint parameter, which allows the Emirates ID or Trade License Number to be sent as a JWE.

Please refer to the OpenAPI description for further details.

4. Error Handling

The error scenarios described above are summarised in the table below.

	Scenario	Description	Action	Redirect User to TPP	Sequence Diagram Step

	Scenario	Description	Action	Redirect User to TPP	Sequence Diagram Step
1	Client Validation Error	Validation of the Client has failed and the TPP cannot therefore be identified.	An error must be displayed to the User in the LFI app.	No	5006
2	Authorization Request Error	Validation of the JWT-Secured Authorization Request or Rich Authorization Request has failed.	The User must be redirected to the TPP who will display an error page.	Yes	5008
3	User Validation Error	The User has not completed authentication and authorised consent, therefore “forcing” an error response to the TPP.	The User must be redirected to the TPP who will display an error page, reflecting the fact that the User did not complete the authorisation of the requested consent.	Yes	6007 6009

The following sections expand on each error type.

4.1 Client Validation Error

Client Validation Errors are returned by Heimdall when the Client belonging to a given TPP cannot be successfully validated.

Readers should note that with the implementation of Pushed Authorization Requests (PAR) for the Open Finance Framework the incidence of Client Validation Errors is likely to low as the Client and, by extension, the TPP will be validated in advance at the PAR Endpoint.

Client Validation Errors are indicated by a 400 Bad Request HTTP response code, with an error response payload that describes why validation failed (please refer to the linked OpenAPI description above for more details). The table below shows the Client Validation Errors returned by the Heimdall API.

	Description	Error Code (`error`)	Error Description (`error_description`)

	Description	Error Code (`error`)	Error Description (`error_description`)
1	The `client_id` query parameter sent by the Client does not match the value stored with the Authorization Request.	`invalid_client`	The `client_id` value does not match the value stored in the Authorization Request.
2	The Client or TPP who owns the Client is no longer in a valid state in the Trust Framework, and therefore cannot be successfully validated.	`invalid_client`	The status of the Client is no longer valid. The Authorization Request can no longer be completed.
3	An internal error has stopped validation of the Client. The validation of the Client cannot therefore be completed authoritatively.	`server_error`	The Client cannot be validated due to an internal error.

4.2 Authorization Request Error

Authorization Request Errors are returned by Heimdall when the Authorization Request is invalid or cannot be processed.

Authorization Request Errors are indicated by a 303 Other HTTP response code, with the error and error_description parameters contained in the response (please refer to the linked OpenAPI description above for more details). The table below shows the Authorization Request Errors returned by the Heimdall API.

	Description	Error Code (`error`)	Error Description (`error_description`)

	Description	Error Code (`error`)	Error Description (`error_description`)
1	The Authorization Request has expired as the number of seconds since the `expires_in` value returned by the PAR Endpoint has passed.	`invalid_request`	The Authorization Request has expired.
2	An internal error has stopped validation of the Authorization Request. The validation of the Authorization Request cannot therefore completed.	`server_error`	Error description will be dependent on the error condition experience at Heimdall.

4.3 User Validation Error

User Validation Errors are returned by Heimdall when the LFI signals that User authentication and authorisation of consent has failed.

User Validation Errors Errors are indicated by a 303 Other HTTP response code, with the error and error_description parameters contained in the response (please refer to the linked OpenAPI description above for more details).

Unlike other error types the LFI must supply the appropriate error and error_description parameters when invoking the doFail operation. The table below shows an example list of the errors that could be set by the LFI to indicate User authentication and authorisation of consent has failed. The LFI is responsible for implementing the correct codes based on this guidance, their understanding of their User authentication and authorisation flows, and adherence to the appropriate OAuth error codes.

	Description	Error Code (`error`)	Error Description (`error_description`)

	Description	Error Code (`error`)	Error Description (`error_description`)
1	The User does not successfully complete Multi-Factor Authentication	`access_denied`	The User failed to authenticate at the LFI in order to authorise consent.
2	The User cannot select one-or-more accounts for account data sharing as no in-scope accounts are available. This example would only happen where the LFI has not implemented the Validate operation described in the API Hub documentation.	`invalid_request`	The User could not authorise consent as no supported accounts are available.
3	The User declines to authorise consent of their own volition.	`access_denied`	The User declined to authorise the requested consent.
4	The LFI experienced an internal error performing User authentication and authorisation and therefore cannot complete the request.	`server_error`	Error description will be dependent on the error condition experienced at the LFI.
5	The LFI cannot complete the User authentication and authorisation journey due to high load at their Authorisation App or Backend	`temporarily_unavailable`	The User could not authenticate or authorise consent due to high load at the LFI.

Please note that if an LFI submits an invalid error code that is not supported by the standards included in the FAPI 2.0 Security Profile the error code will be overwritten with invalid_request.

API Hub Documentation v6

Authorisation Server API Guide