Error catalogue
Every problem type the API returns (RFC 9457 application/problem+json). Branch on code; type is https://api.banking.wirebloom.com/problems/{slug}. See Errors for handling and retries.
| Status | Code | Title | Retryable | What it means |
|---|---|---|---|---|
| 400 | bad_request | Bad request | No | The request is malformed (syntax, unknown parameter or body that is not JSON). |
| 400 | invalid_cursor | Invalid cursor | No | The pagination cursor is invalid or belongs to another sort / filter. |
| 400 | refresh_token_reused | Refresh token reused | No | Token endpoint: a rotated refresh token was presented again and its family was revoked (errors[0].code=invalid_grant). |
| 400 | unknown_filter | Unknown filter | No | A filter[...] parameter names a field the operation does not filter on. |
| 401 | invalid_api_key | Invalid API key | No | The API key is unknown, revoked or past expiresAt. |
| 401 | invalid_credentials | Invalid credentials | No | Login failed (interactive sign-in only). |
| 401 | invalid_signature | Invalid signature | No | An inbound webhook signature did not verify. |
| 401 | mfa_required | Multi-factor authentication required | No | Multi-factor verification is required to finish signing in (interactive only). |
| 401 | session_expired | Session expired | No | The interactive session expired; sign in again. |
| 401 | unauthenticated | Authentication required | No | No valid credentials: send Authorization: Bearer <key>. |
| 403 | access_rejected | Access rejected | No | The customer's registration access was rejected by staff (customer registration, spec 2026-09-28); the account cannot sign in until it is reversed. |
| 403 | dual_control | Dual control required | No | The action needs a second person (four-eyes) to approve it. |
| 403 | forbidden | Forbidden | No | The caller lacks the capability the operation requires. |
| 403 | impersonation_restricted | Not allowed while impersonating | No | Staff impersonating a user may not perform this action. |
| 403 | insufficient_scope | Insufficient scope | No | The API key does not carry a scope listed in the operation's x-api-key-scopes. |
| 403 | ip_not_allowed | IP address not allowed | No | The request came from an address outside the key's ipAllowlist. |
| 403 | reason_required | Access reason required | No | Platform staff must give an access reason for this tenant. |
| 403 | step_up_required | Step-up authentication required | No | A fresh step-up verification is required for this action (sessions only; API keys skip step-up). |
| 403 | tenant_forbidden | Tenant not allowed | No | X-Tenant-Id names a tenant the credentials are not bound to. |
| 403 | terms_outdated | Terms acceptance required | No | The user must accept the current terms first. |
| 404 | feature_disabled | Feature disabled | No | The feature is not enabled for this operator or environment (for example sandbox simulations in production). |
| 404 | not_found | Not found | No | The resource does not exist or belongs to another tenant (existence is never revealed). |
| 405 | method_not_allowed | Method not allowed | No | The path exists but not with this HTTP method. |
| 409 | activation_blocked | Activation checklist incomplete | No | A banking connection cannot be activated while a blocking checklist step is open. |
| 409 | conflict | Conflict | No | Generic conflict with the current state when no specific 409 type applies. |
| 409 | connection_in_use | Connection in use | No | A banking connection still holds balances, settlement money, in-flight items or active mandates. |
| 409 | domain_not_approved | Email domain not approved | No | The email domain is not on the customer's approved list. |
| 409 | duplicate_recipient | Duplicate recipient | No | A recipient with the same bank details already exists. |
| 409 | funds_requests_disabled | Funds requests disabled | No | Funds requests are disabled for this customer. |
| 409 | idempotency_key_in_use | Idempotency key in use | Yes | A request with the same Idempotency-Key is still running; retry after Retry-After. |
| 409 | insufficient_funds | Insufficient funds | No | The balance cannot cover the amount plus fees. |
| 409 | invalid_transition | Invalid state transition | No | The resource is not in a state that allows this action. |
| 409 | last_mfa_factor | Last MFA factor | No | The last MFA factor of a user cannot be removed. |
| 409 | not_cancellable | Not cancellable | No | The resource can no longer be cancelled. |
| 409 | onboarding_not_open | Onboarding not open | No | Onboarding is not open yet: the operator's onboarding mode is prepare (customer registration, spec 2026-09-28), so KYB submission and identity verification wait until launch. |
| 409 | primary_owner_protected | Primary owner protected | No | The primary owner cannot be removed or demoted. |
| 409 | provider_unsupported | Not available on this banking connection | No | The operator's active banking connection does not offer this feature (for example open-banking consents or provider costs on a partner that lacks them); do not retry. |
| 409 | quote_expired | Quote expired | No | The FX quote expired; request a new quote and retry with it. |
| 412 | precondition_failed | Precondition failed | No | If-Match does not match the current ETag: re-read the resource and apply your change again. |
| 413 | payload_too_large | Payload too large | No | The request body exceeds the limit (1 MiB for JSON). |
| 415 | unsupported_media_type | Unsupported media type | No | Send Content-Type: application/json (or the media type the operation documents). |
| 422 | currency_not_enabled | Currency not enabled | No | The currency is not enabled for this customer or operator. |
| 422 | document_not_clean | Document not clean | No | The document has not passed the malware scan (yet). |
| 422 | idempotency_key_reused | Idempotency key reused | No | The Idempotency-Key was used within 24 h with a different body. |
| 422 | limit_exceeded | Limit exceeded | No | The operation exceeds a payment or customer limit. |
| 422 | recipient_not_approved | Recipient not approved | No | Payments need an approved recipient. |
| 422 | validation_error | Validation failed | No | One or more fields are invalid; see errors[] (JSON Pointer field, code, message). |
| 422 | verification_unavailable | Verification unavailable | No | Account-holder verification is not available for this destination. |
| 428 | precondition_required | Precondition required | No | Updates of versioned resources need If-Match with the ETag from your last read. |
| 429 | rate_limited | Too many requests | Yes | Too many requests for the key's bucket; wait for Retry-After and back off with jitter. |
| 500 | internal_error | Internal error | Yes | Unexpected server error; retry with the same Idempotency-Key and quote requestId if it persists. |
| 501 | not_implemented | Not implemented | No | The routed banking partner does not offer the operation (for example a recall on a rail without recalls). |
| 502 | provider_error | Provider error | Yes | The banking partner returned an error; retry with the same Idempotency-Key. |
| 503 | service_unavailable | Service unavailable | Yes | The service is temporarily unavailable; retry with backoff. |
| 504 | provider_timeout | Provider timeout | Yes | The banking partner did not answer in time; retry with the same Idempotency-Key. |