Errors - codes reference

Every error response carries a stable machine-readable code:

{
  "error": { "code": "refresh_cooldown", "message": "…", "nextRefreshPossibleAt": "…" },
  "requestId": "req_8f3a2c1e"
}

Branch on error.code only. error.message is human-readable and may change without notice - parsing it will break your integration. Any other field in the error body is informational. 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 /v2/partner/config.
operation_temporarily_unavailable	403	The operation is currently not allowed; retry later.
connection_not_recoverable	400	The connection is Disabled and cannot be reconnected - create a new one.
consent_inactive	403	The connection's consent is no longer active - offer the user a reconnect.
not_found	404	Unknown resource (or not yours).
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.
conflict	409	The request conflicts with the current state of the resource. Re-read the resource before retrying.
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.
pilot_provider_not_allowed	403	The provider is not reachable with this key: sandbox keys (bb_test_…) reach sandbox providers (*_xf) only; live keys reach the real catalog.
sandbox_provider_not_allowed	403	The provider is a sandbox provider (*_xf) and the key is a live key (bb_live_…). Live connections are real; use a bb_test_… key to test against the sandbox.
pilot_connection_cap_reached	409	The cap on concurrently active real connections for this key is full. Revoke a connection you no longer need.
application_not_active	403	Your application is not activated, so it cannot open bank connections. Check its state in the portal.

These two codes are returned only by POST /v1/connections and POST /v1/connections/{connectionId}/reconnect, which fingerprint the request behind an Idempotency-Key:

error.code	HTTP	Meaning / how to react
idempotency_key_reused	422	The Idempotency-Key was replayed with a different request body or X-Client-Id. Use a new key for a new request.
idempotency_key_in_use	409	The first request with this Idempotency-Key is still in flight. Retry after it has answered; the retry replays its response.

Notes:

• 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.