Errors — codes reference

Every error response carries a stable machine-readable code:

{
  "errorDesc": "…legacy human text…",
  "error": { "code": "refresh_cooldown", "message": "…", "nextRefreshPossibleAt": "…" },
  "requestId": "req_8f3a2c1e"
}

Branch on error.code only. errorDesc and error.message are human-readable and may change without notice — parsing them will break your integration. Every response also carries an X-Request-Id header (echoed as requestId) — include it when contacting support.

The SDKs surface all of this as typed errors (PartnerApiError.code, .httpStatus / .http_status, .requestId / .request_id).

Codes

error.code	HTTP	Meaning / how to react
validation_error	400	Malformed request (missing field, bad format). Fix the request; do not retry as-is.
unauthorized	401	Missing/invalid X-Api-Key. Check the key and its mode (bb_test_ vs bb_live_).
capability_disabled	403	The capability (refresh/reconnect/…) is not enabled for your partner config — see GET /v1/partner/config.
operation_temporarily_unavailable	403	The operation is currently not allowed; retry later.
consent_inactive	403	The connection's consent is no longer active — offer the user a reconnect.
not_found	404	Unknown resource (or not yours).
connection_not_recoverable	400	The connection is Disabled and cannot be reconnected — create a new one.
refresh_in_progress	400	A refresh is already running; wait for its webhook.
refresh_cooldown	400	Too soon since the last refresh. error.nextRefreshPossibleAt says when.
refresh_quota_exceeded	400	Daily refresh quota reached. error.nextRefreshPossibleAt says when.
background_refresh_not_allowed	406	The bank requires user presence. Side effects: the connection is inactivated and a consent webhook follows. Never retried by the SDKs.
rate_limited	429	Rate limit hit; honor the Retry-After header (the SDKs do).
internal_error	5xx	Our fault. The SDKs retry idempotent calls with backoff; if it persists, contact support with the requestId.

Notes:

• refresh_cooldown and refresh_quota_exceeded are indistinguishable today (same backend guard); both carry nextRefreshPossibleAt.
• 401/429 are produced at the gateway and may not carry the full envelope — the SDKs fall back to status-derived codes.
• The SDKs retry only 429 and 5xx, and POSTs only under an Idempotency-Key; 4xx codes are never retried.