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

Sample Error Responses:

The user cancels the ID verification flow at any point (applicable to bank ID verification and document scanning).

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

The web session for the Interac Hub has expired. Note that the session begins when the user is first redirected from the relying party to the Hub landing page, and ends when the user is redirected from the final Hub page back to the relying party. This timeout can be customized during onboarding with the sessionTimeoutOverride parameter (5-60 minutes).

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

The financial institution selected by the user was unable to retrieve all required fields (e.g. birthdate).

https://redirect_uri?error=access_denied&error_description=Service%20error&locale=en-CA&state=bee48cf1eb0c40ec817df458e0cb4cb6

The user scans a document which is flagged as SUSPECTED.

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

The user scans a document which is flagged as REJECTED.

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

Returned in Dual Mode if the user completes the bank authentication flow, but the document verification flow failed with a flagged SUSPECTED document.

https://redirect_uri?error=access_denied&error_description=Verified.Me%20completed%20and%20Document%20S&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:

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'."
}