API DocumentationError Code Glossary
Last updated 7 months ago
Error Code Glossary
This glossary provides a reference for common error messages returned by the API, along with their descriptions and suggested actions.
🧾 Error Reference Table
| HTTP Code | Error Message | Description | Suggested Action |
|---|---|---|---|
| 400 | Missing field 'accountId' | Required field is missing | Verify request parameters |
| 400 | No parent account with matching currency found | Your client does not have the required Parent account for the requested VAS currency | Ask BCB to provision the Settlement and Parent account pair for that currency |
| 400 | Bad Request during a VAS Sub -> Sub transfer | The requested VAS flow is not allowed even if both accounts are in the same currency | Use only supported VAS flows and read the VAS API Flows guide |
| 401 | Invalid credentials | Authentication failed | Re-authenticate using valid credentials |
| 403 | IP address not allowed | Request made from non-whitelisted IP | Check and update IP restrictions |
| 403 | Forbidden | Client is authenticated but does not have permission for this resource | Verify user or token permissions |
| 404 | Account not found | Resource could not be located | Ensure account ID or endpoint is correct |
| 409 | ACCOUNT_NAMES_IMMUTABLE | Immutable allocation fields were changed after the first update of a virtual account | Only update clientReference after allocation; do not change identity fields again |
| 409 | Duplicate transfer request | Conflict with current state | Use idempotency or retry with care |
| 429 | Rate limit exceeded | Too many requests in the time window | Wait and retry after retry_after time |
| 500 | An unknown error occurred | Internal server error | Try again or contact support |
For VAS-specific diagnostics, see the Virtual Accounts Troubleshooting guide.
Was this helpful?