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


Where it occurs

What it means

Recommended action

Invalid credentials

On "Create connection"

Only occurs on verify-credentials step.

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 Create Connection request.

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.

Invalid credentials

On "Refresh connection"

Can occur on verify-credentials step when you make a request to refresh a users connection.

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 Update Connection request.


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

When creating or updating a connection

Can occur when making a POST or UPDATE request to the connections endpoint,

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 /jobs endpoint to monitor the status of this job (note polling should be done at much longer intervals than the standard job polling as retries are attempted every 2 hours).

At all other times

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 /institutions endpoint: if it is major-outage then the problem is widespread and you should alert your user, and wait until the status has lifted

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 connection-id to Basiq's support team, to investigate.


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.