How to recognise and handle end user authentication errors

This short guide is to help you understand what errors an end user can encounter during their authorisation flow, how to communicate them to the user, and what action to take next.

Identifying the errors:

As you create a requisition (step 4 of the guide) to connect a user, you provide a redirect URL:

POST /api/v2/requisitions/
{
"institution_id": "SEB_UNLALV2X",
"reference": "something-unique-111",
"redirect": "https://www.example.com",
}

Once you redirect the user to the "link" in the response, they will undergo authentication at the bank. After they are have authorised access, they will be redirected back to you, to the URL you provided with the "reference" passed as a "ref" param:

https://www.example.com?ref=something-unique-111

Sometimes an error occurs during the authorization flow. Let's use an example where the users clicks the cancel (X) button, thus interrupting the flow and returning to you. In this case they have caused the UserCancelledSession error, and the exact error will be appended to the redirect URL:

https://www.example.com?ref=something-unique-111&error=UserCancelledSession&details=User+cancelled+the+session.

This way you can identify the error and take appropriate action.

How to handle the errors

Type	Detail	Explanation	User message suggestion
UnknownError	An unknown error occurred.	Not yet defined authorisation errors from the bank.	"Something went wrong, please contact support"
SSNVerificationFailed	SSN Verification has failed	The SSN you have provided does not match the SSN known to the bank.	"The SSN you provided is wrong, please enter the correct one and restart the process"
InstitutionTechnicalError	A technical error occurred while trying to connect to the institution, please try again.	Errors that indicate temporary issues with ASPSP handling the request, such as downtime or random server errors.	"Something went wrong at the bank. Please try again and contact support if you get the same error"
GoCardlessTechnicalError	An unexpected error occurred in the GoCardless system. If this error persists, please contact support.	Not yet defined authorisation errors in GoCardless. We have been alerted to it and will triage it accordingly. Reporting it helps.	"Something went wrong with the data connection provider (GoCardless).Please try again and contact support if you get the same error"
UserCancelledSession	User cancelled the session.	Errors that suggest the PSU canceled the session.Also covers cases where the PSU broke the flow by pressing the back button, refreshing the page, etc.	"The flow was cancelled. Try again without clicking cancel (x), reloading the page or pressing back"
UserSessionRejected	User session rejected due to incorrect credentials or a business exception	Situations where either incorrect credentials were provided or a business exception has occurred. Examples include the PSU being a minor or not having PSD2 compliant accounts.	"The bank does not allow you to authorise access - make sure you have entered the correct credentials, and you have permissions to grant access. Contact your bank if you get the same error"
NoAccountsConnected	No Accounts available after authorization.	When the bank returns an error if there are no compliant accounts. If bank returns empty list instead, there is no error.This error is extremely rare, you can omit handling it.	"No accounts have been found, please contact support or your bank"
ConsentLinkReused (RequisitionLinkReused)	This link has already been used for authorization and is no longer valid.	The requisition is either linked (LN) and you have access to the accounts.Or the requisition is expired (EX), and you need to create a new one to re-establish a connection	"You followed the link that you have already used before. Please [the action that you expect form your user to either restart the process or trigger the data sync]"
InstitutionUnavailable	The bank is not available at the moments because it is suspended in the GoCardless system.	The bank you are trying to connect to is not available at the moment. Either we are working on bringing it back online, it has merged with another bank, or went out of business.	"The bank you are trying to connect to is not available at the moment"