Errors and limits
The typed errors the v2 SDK throws, their codes, and the rate limits all keys in an organisation share.
Errors
Section titled “Errors”The SDK throws typed errors. Each one is a CeremonyError with a stable code. Branch on the class or the code.
import { ApprovalNotGivenError, CeremonyError } from '@banklink/sdk/v2';
try { await banklink.profiles.sync(id);} catch (error) { if (error instanceof ApprovalNotGivenError) askThemToApproveAndRetry(); else if (error instanceof CeremonyError && error.code === 'rate_limited') retryLater(error); else throw error;}| Error | code |
Meaning |
|---|---|---|
KeyRequiredError |
key_required |
No customer key was configured, or your organisation hasn’t registered one. Run keys.init |
KeyMismatchError |
kid_mismatch |
The seed doesn’t match the customer key registered for your organisation, or the saved connection |
OtpRequiredError |
otp_required |
The bank asked for a one-time PIN and there was no onOtp |
BankLoginFailedError |
bank_login_failed |
The bank refused the login |
OnlineBankingDisabledError |
online_banking_disabled |
Online banking is switched off for this profile (Capitec). The account holder switches it on in the bank’s app, then you retry. A subclass of BankLoginFailedError |
ApprovalNotGivenError |
approval_not_given |
The account holder didn’t approve the sign-in in their banking app in time |
JobExpiredError |
job_expired |
The job ran out of time. Start a new one |
TicketInvalidError |
ticket_invalid |
The signed job details failed verification. Don’t retry. Contact support |
CeremonyError |
any | The base class. Other codes are below |
Other codes on CeremonyError:
code |
Meaning |
|---|---|
unauthorized |
Missing or invalid API key |
forbidden |
The API key doesn’t have v2 turned on. See API keys |
test_key_not_supported |
Test keys can’t use v2 |
ip_not_allowed |
The key is restricted to IP addresses, and this call came from another one |
rate_limited |
Over a limit. retryAfterMs says when to try again |
worker_busy |
The bank-connection worker is busy or unavailable. Try again shortly |
profile_not_found |
No saved connection with that ID |
otp_limit |
More than 3 one-time PINs in one job |
cancelled, timeout |
The job was cancelled through signal, or ran past timeoutMs |
v2 never returns raw bank or server messages. Keep logins, one-time PINs, seeds and results out of your logs.
Limits
Section titled “Limits”All keys in an organisation share these:
| Limit | Value |
|---|---|
| API requests | 60 a minute. Job polls are counted separately |
| Bank logins | 10 a minute |
| Logins per saved connection | 3 in 10 minutes |
Over a limit you get rate_limited with retryAfterMs. The SDK retries waits of 15 seconds or less on its own. A refused request did nothing, so it is safe to send again after the wait.