Skip to content

Banklink v2Customer-held keys and one-off fetches, through the Node.js SDK. v1 is unchanged.Migration guide

Banklink Docs

Errors and limits

The typed errors the v2 SDK throws, their codes, and the rate limits all keys in an organisation share.

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.

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.