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 use the /job endpoint, checking on the status of each step to see if there have been any failures.
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 "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 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 1 year ago