Handling Jobs
Keeping track of jobs
Providing your users with a simple, intuitive and informed experience is key to good UX.
To help keep you and your users informed we provide job status and error messages which your Support teams can use to troubleshoot issues and pass directly onto the user (i.e. in cases of invalid credentials).
To do this, you can poll the /job endpoint, checking on the status of each step until the job has either
- successfully completed the relevant step/s;
- failed at any of the steps.
What to do when a job fails
The best case scenario, is that all job steps will have completed successfully. In practice, live banks present a number of scenarios that prevent Basiq from fetching a user's accounts and transactions from their internet banking. In the event that a step has failed, the result object will contain an embedded error object, and the information within that will determine how you clear the issue and fetch their data successfully.
Possible job failure scenarios
Scenario | Where it occurs | What it means | Recommended action |
|---|---|---|---|
On "Create connection" | Only occurs on If you're using the BasiqConnect Simple UI, it is handled for you | If the bank returns detail of the failure (e.g. The user is locked out of internet banking, or there is an MFA challenge that isnt supported), Basiq will return this detail. If no detail is given, Basiq will return a generic error. | For a generic error, retry the The user may need to log into their banking via the browser, not the app, to confirm they can access with the credentials they have provided to Basiq. If the error detail specifies that MFA is not supported, they can try to login without MFA through their internet banking, and if they are successful, try again through Basiq. |
On "Refresh connection" | Can occur on | This could happen for the same reasons as "Create connection", but could also be that your user has changed their internet banking password. | When your user returns to your application, prompt them to resubmit their credentials, and update these using the |
| Can occur on any job step, depending on where Basiq encounters the error when navigating the user's internet banking | The bank is presenting a popup to the user in their internet banking. Whenever possible Basiq will navigate through these, but for example if the bank presents new T&Cs to the user and offers only options to "Agree" or "Decline", then Basiq will fail the job with this error | Ask your user to login to their internet banking, navigate to accounts and transactions, and address any CTA's/popups requiring action from the bank You/your application can then refresh the connection. If the popup has cleared, the job should complete as normal |
| Can occur when making a | Due to failure in either the financial institution or the Basiq connector. | Basiq's connection retry mechanism will kick in, meaning the job will be placed in a queue to be retried every 2 hours until either it is successful, or expires (after 7 days). You can let the user know there is a problem fetching data from their bank, and that you will let them know when their data is ready. In the meantime you can use the |
| Can occur on any job step, depending on where Basiq encounters the error condition on the bank's internet banking portal. | The bank is unable to service Basiq's request This is typically due to a maintenance outage or performance issue on the bank's website, but can occasionally happen if the bank has made significant changes to their internet banking | You can let the user know there is a problem fetching data from their bank, and that you will let them know when their data is ready. Check the status for this bank in the If the institution status is anything other than major-outage then wait 10 minutes and try again. If, after a couple of retries, the error has not cleared, then report the |
Sandbox users for testing job failure scenarios
We have created test users especially for replicating these failure scenarios in your user flow. These three users will always fail on the same job steps. You can find them here.
Avoiding duplicate jobs
If you attempt to create or refresh a connection while a job is either queued or still in progress, the API will return a 200 status with the original job instead of a newly created job.
Updated over 2 years ago