Skip to main content

Errors handling

The statuses​

The management of error cases requires taking into account the type of channel (Redirect or Embedded), the type of sync (automatic or manual) or a bad action by the user.

It will thus be necessary to interact with the user in cases where a strong authentication is requested (the most common case), he must change his password, or more rarely, when a specific action is required by the bank. Without these actions, synchronisations will not continue to run normally, as access to bank data is not allowed by the bank.

The status of the connection for the last synchronisation performed (automatic by Linxo or manual by the partner) indicates whether it was successful: SUCCESS, FAILED or PARTIAL_SUCCESS.

In case of error, the channel status indicates the type of error.

These statuses can be retrieved via different channels:

  • The API with the GET connections
  • The webhook, which also retrieves connection information at each account synchronisation.
  • The management of events in the widget (web events) or via a queue, can also be used to retrieve information in real time.

The main error statuses available in the channel are:

  • TOKEN_EXPIRED: The bank's PSD2 API token has expired
  • PASSWORD_CHANGE_REQUIRED: The bank requests a password change
  • CHALLENGE_REQUIRED requested by the bank to perform a strong authentication (by SMS for example): The last synchronisation failed because the bank requested a challenge (by SMS, email, ...). The user was not the initiator of the synchronisation.
  • USER_ACTION_REQUIRED: The bank asks the user to perform an action (accept the terms and conditions, fill in a form, ...). Access to the accounts will only be possible after the user has validated this action. The user must therefore be asked to log on to the bank's website.

The error management​

The widget entry points for error handling are mainly:

  • 'edit_credential' for managing passwords. The widget handles ‘REDIRECT’ or ‘EMBEDDED’ channels as needed.

For a TOKEN_EXPIRED, we can thus call the widget as follows, specifying the Redirect channel (PSD2):

https://sandbox-embed.oxlin.io/v2.1/widget/edit_credentials?session_id=_DFRTDSERS-FRX-EI8bdTrfE5TkoGI&connection_id= 46666&expected_account_types=PAYMENT&provider_id=1002

1002 is the identifier of agricultural credit, 100201 the redirect channel of the CA

  • 'user_input' for the challenge when managing a queue and its events and therefore in the context of manual synchronizations.

This makes it possible to manage the bank's challenge request in real time.

This can be done by parsing the events in the queue (SYNC_ALL_USER_INPUT_REQUESTED, LIST_ACCOUNTS_USER_INPUT_REQUESTED, …) and presenting the user with the widget's GUI allowing them to enter this code. This is a fairly complex command to implement.

  • In case events are not used, for reasons of simplicity and/or to manage CHALLENGE_REQUIRED or CHALLENGE_TIMED_OUT statuses, it is also possible to use the edit_credential widget function. The challenge will thus also be managed by the widget.

In terms of managing passwords and challenges, it is also necessary to manage cases of error:

  • AUTH_FAILED (scraping): authentication failed during last sync
  • TOO_MANY_ATTEMPTS: Authentication failed multiple times. Requires user authentication again for syncs to start again
  • CHALLENGE_TIMED_OUT,
  • CHALLENGE_FAILED,
  • CHALLENGE_CANCELLED

The errors list is available in the reference documentation when you retrieve a connection in the ‘status’ field at the ‘connection’ and ‘channel’ levels: Get all connections

When a connection is created in account consent mode (with the 'consent_per_account' parameter of the add_connection API command), the widget offers the user an interface allowing him to select the accounts he wishes to synchronize (on the 2 channels Redirect and Embedded). In this state, the account status is 'PENDING_CONSENT'.

If the user leaves the widget without making a selection, the accounts status of the connection does not change and remains in 'PENDING_CONSENT'. Financial data is therefore not retrieved during automatic synchronizations of the connection.

It is then necessary to finalize the creation of the connection by presenting the user with the account selection interface again. This is done with the ‘manage_accounts’ of the widget API endpoint.