The Interac Hub supports error messages returned according to the HTTP request method/endpoint used. Below are descriptions of some of the most common error messages.

Error Handling Approach: It is recommended that the Relying Party capture these error messages and display user-friendly screens notifying the user of an error and provide options to move forward/recover. It is also considered good practice for the Relying Party to have an error handling mechanism to handle unrecognized error messages (i.e. in the event new error messages are implemented down the road) and to provide the user options to move forward/recover.

For a full list of errors returned by the Hub API, refer to Appendix: Error Codes (KB article: access restricted).

Errors for requests to authorization_endpoint

Errors adhere to RFC 6749 4.1.2.1 Error Response returned to the RP/DAC through the front channel via the user agent (i.e. web browser) using the redirect_uri specified during the request to the Hub authorization_endpoint. These typically occur in cases where the RP/DAC API requests are malformed or there was an error in processing (e.g. user cancels the ID verification flow, invalid documents are scanned, etc.). The RP/DAC should include logic in the redirect_uri to handle resulting errors and take any needed action (i.e. informing the user, redirecting the user to a page to try the flow again, etc.). The format used is:

http://redirect_uri?error=title+of+error+message&error_description=a+description+of+the+error&locale=en-CA&state=state_val

Parameter	Example Value	Description
`error`	`access_denied`	An error code conforming to RFC 6749 4.1.2.1 Error Response indicating the nature of the error
`error_description`	`User+cancelled`	An error message indicating which part of the Hub flow failed
`locale`	`en-CA`	Language chosen by the end user
`state`	`bee48cf1eb0c40ec817df458e0cb4cb6`	The state value used during the initial authorization request

Interac Hub General (flow-independent) Error Responses:

User cancels flow on Interac Hub screens.

https://redirect_uri?error=access_denied&error_description=User+cancelled&locale=en-CA&state=bee48cf1eb0c40ec817df458e0cb4cb6

User times out (unable to complete the flow) on Interac Hub screens before duration specified in 'sessionTimeoutOverride' configuration parameter.

https://redirect_uri?error=session_expired&error_description=The+session+has+expired&state=bee48cf1eb0c40ec817df458e0cb4cb6

Interac Verification Service (IVS)-specific Error Responses:

User failed financial institution verification and/or financial institution unable to to retrieve all required fields.

https://redirect_uri?error=access_denied&error_description=Service+error&state=bee48cf1eb0c40ec817df458e0cb4cb6

Interac Document Verification Service (IDVS)-specific Error Responses:

The user scans a document which is flagged as SUSPECTED. The parameter 'allowPartialResults' set to 'false'.

https://redirect_uri?error=access_denied&error_description=Document+S&locale=en-CA&state=bee48cf1eb0c40ec817df458e0cb4cb6

The user scans a document which is flagged as REJECTED. The parameter 'allowPartialResults' set to 'false'.

https://redirect_uri?error=access_denied&error_description=Document+R&locale=en-CA&state=bee48cf1eb0c40ec817df458e0cb4cb6

Interac IVS + IDVS "Dual Mode"-specific Error Responses:

User cancels both IVS and IDVS flows.

https://redirect_uri?error=access_denied&error_description=Verified.Me+cancelled+and+Document+cancelled&locale=en-CA&state=bee48cf1eb0c40ec817df458e0cb4cb6

User cancels IVS flow and IDVS flow suspected.

https://redirect_uri?error=access_denied&error_description=Verified.Me+cancelled+and+Document+S&locale=en-CA&state=bee48cf1eb0c40ec817df458e0cb4cb6

User cancels IVS flow and IDVS flow rejected.

https://redirect_uri?error=access_denied&error_description=Verified.Me+cancelled+and+Document+R&locale=en-CA&state=bee48cf1eb0c40ec817df458e0cb4cb6

User completes IVS flow and IDVS flow suspected.

https://redirect_uri?error=access_denied&error_description=Verified.Me+completed+and+Document+S&locale=en-CA&state=bee48cf1eb0c40ec817df458e0cb4cb6

User completes IVS flow and IDVS flow rejected.

https://redirect_uri?error=access_denied&error_description=Verified.Me+completed+and+Document+R&locale=en-CA&state=bee48cf1eb0c40ec817df458e0cb4cb6

Errors for requests to token_endpoint and userinfo_endpoint

Errors are returned in JSON and typically includes the following keys:

Parameter	Example Value	Description
`error`	`an_error_code`	An error code indicating the nature of the error
`error_description`	`A humanly-readable error message`	An error message indicating the specifics of the failure

Sample Error Responses:

An invalid authorization code is used at the Hub token_endpoint.

{
    'error': 'invalid_grant',
    'error_description': 'The provided authorization grant (e.g., authorization code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client.'
}

An invalid access_token is used at the Hub userinfo_endpoint.

{
    "error": "request_unauthorized",
    "error_description": "The request could not be authorized. Check that you provided valid credentials in the right format."
}

An expired access_token is used at the Hub userinfo_endpoint.

{
    "error": "invalid_token",
    "error_description": "Token expired. Access token expired at '2023-02-10 19:22:15 +0000 UTC'."
}