Errors

The BVNK API responds with detailed information in the event of a failed request. Below is a comprehensive list of payment error codes, along with brief descriptions on how to address them. This resource serves as a valuable reference for developers, enabling them to efficiently troubleshoot and address errors in their applications' integration with BVNK's API.

The errors are returned in the following format:

JSON

{
    "code": "bvnk:payment:0005",
    "status": "Bad Request",
    "traceId": "abc123-def456-ghi789",
    "message": "Beneficiary details validation failed",
    "details": {
        "documentLink": "../api-overview/errors",
        "errors": [
            "Address country required"
        ]
    }
}

Array of Errors

{
    "requestId": "cd8b277efeeccdea4067a4030ecc4e45",
    "errorList": [
        {
            "requestId": null,
            "code": "MER-PAY-2012",
            "parameter": "amount",
            "message": "insufficient funds"
        }
    ]
}

Here,

• code: URI reference identifying the error type (e.g. bvnk:payment:0005). See the list of codes and descriptions below.

• status: HTTP status code name, such as Bad Request, Forbidden.

• traceId: Tracing ID useful for searching in logs when shared by a customer with support.

• message: Human-readable explanation of the error and guidance on how to resolve it. In most cases, error details are propagated into this field.

• details: Structured information about why the request failed. This field is most common for Bad Request (400) errors, but it can be null when the details have been propagated to the message or are otherwise unavailable.

  For example, the above payout response appears if you specify countryCode: null in the request. The errors array contains specific information about the missing field.

• details.documentLink: Link to this article where you can learn more about the caught error.

0001-0099

Fiat payouts

Code	Message	Description
BVNK:PAYMENT:0001	Received Bad Request	The system received a request with invalid parameters or missing required information. Check the request format, parameters, and ensure all required fields are correctly filled.
BVNK:PAYMENT:0002	Payout with the given identifier could not be found	The system was unable to locate the requested payout using the provided ID. Verify that the payout ID is correct and exists in the system.
BVNK:PAYMENT:0003	Forbidden → received request with wrong authentication details	The request was rejected due to an authentication failure. Ensure your API keys, tokens, or credentials are valid and correctly included in the request header.
BVNK:PAYMENT:0004	Error while receiving or validating beneficiary	The beneficiary details could not be retrieved, or failed validation checks. This may occur due to missing or malformed fields (name, address, account identifiers), failed KYC/KYB or sanctions screening, or temporary downstream connectivity errors. Verify beneficiary data to ensure the required fields and formats (e.g., IBAN/ABA) are accurate. Confirm the beneficiary is allowed, and retry once issues are resolved.
BVNK:PAYMENT:0005	Validation of the beneficiary has failed	The beneficiary did not pass mandatory validation rules. Typical reasons include invalid account identifiers, an unsupported destination, a mismatched currency/network, or a compliance screening failure. Correct the beneficiary information (names, address, account numbers, tags/memos where required) or select a different, validated beneficiary before retrying.
BVNK:PAYMENT:0006	Payout with the idempotency key already exists	A payout using the provided idempotency key already exists. For idempotent safety, the platform rejects creating a new payout with the same key. If you intend to retry the same request, use the original response; otherwise, generate a new, unique idempotency key for a new payout.
BVNK:PAYMENT:0007	Insufficient funds	A wallet does not have sufficient funds to complete the requested transaction.
BVNK:PAYMENT:0008	The payment method is not supported	The platform does not currently support the payment method specified in the request. Review the documentation for a list of supported payment methods.
BVNK:PAYMENT:0009	Specific functionality is not enabled for this account or wallet	The specific functionality or flow is not enabled or provisioned for this account or wallet. Check your permissions and product enablement. If the feature is available, enable it in the portal; otherwise, contact support to request access.
BVNK:PAYMENT:0010	The virtual account has been disabled for this given wallet. Customer should use a different wallet or choose different payment method.	The virtual account assigned to the specified wallet is disabled. Use a different wallet or select an alternative payment method. If you need this virtual account re-enabled, review the wallet configuration and contact support or your account manager.
Mass Payouts
BVNK:PAYMENT:0030	Could not find a single payment within a given payout batch	The referenced payout batch contains no payments matching your query, or the payments have not been associated with the batch yet. Verify the payout batch identifier, ensure the batch was created successfully, and confirm that items were added and not removed by validation. If you are filtering, check the date/status filters to ensure you are querying the correct environment (sandbox vs. production).
BVNK:PAYMENT:0031	Could not find specific payout batch	The payout batch could not be located. The batch identifier may be invalid, belong to another account, or the batch may have been archived/expired. Double-check the batch ID/token and your account permissions, then try again. If the batch was created recently, allow a short delay and retry.
BVNK:PAYMENT:0032	Cannot delete a single payout from a batch, as it has started processing already	Once batch processing has started, individual payouts become immutable. Deletions are only permitted while the batch is in a pre‑processing state. To remove items, cancel the whole batch if supported, or create a new batch without the unwanted payout.
BVNK:PAYMENT:0033	Cannot update a single payout from a batch, as it has started processing already	Individual payout updates are blocked after batch processing begins. Modify items only before submission. If you need changes, cancel the batch (where supported) and recreate it with corrected payout details, or submit a follow‑up adjustment as a new payout.

Fees

Code	Message	Description
BVNK:FEES:0001	Invalid wallet selected on client request.	The wallet selected in the client request is invalid. Check that the wallet identifier is correctly formatted and belongs to a valid wallet type.
BVNK:FEES:0002	Provided wallet not found for a specific account.	The system was unable to find the specified wallet associated with the requested account. Verify that the wallet exists and is correctly linked to the account.
BVNK:FEES:0003	Invalid customer fee wallet configuration.	The customer fee wallet configuration contains invalid settings or parameters. Review and correct the fee wallet configuration in your account settings.

---

1000-1999

Code	Message	Description
MER-PAY-1000	Not authorized to perform this action	A user or merchant is not authorised to perform the requested action. This can occur due to insufficient permissions or invalid authentication credentials.

Customer onboarding

Returned by the Customers API v.2 endpoints (/platform/v2/customers) and the customer agreements endpoints (/platform/v2/agreements).

Code	HTTP status	Message	Description
bvnk:onboarding-accounts:1000	400, 403, 404, 405, 415, 500	Varies by error, for example Validation failed. Server errors: Unexpected error - please contact administrator	Generic error returned when no more specific code applies. Common causes are a request body that isn't valid JSON, failed field validation, a missing parameter, an unsupported HTTP method or content type, or credentials without access to the resource. For 500 errors, contact support and include the traceId.

---

2000-2999

warning

Should you encounter any of the errors outlined in this section, be aware that your payment or transaction attempt will not be successful. The system will reject the transaction at the API level, consequently preventing the creation of a failed transaction record. Therefore, you will not find any evidence of the unsuccessful operation within the Portal.

Code	Message	Description
MER-PAY-2000	Invalid parameter value	The request parameters fail validation. This includes JSON parsing errors, missing required parameters, invalid data types, or constraint violations on request fields.
MER-PAY-2001	Amount x.xx <currency> failed is less than minimum limit of x.xx <currency>	The payment amount fails validation. This occurs when the amount is below the minimum limit or above the maximum limit for the specified currency.
MER-PAY-2002	Payment has no quote	An error occurs when a payment operation requires an exchange quote, but none is found. This typically occurs when attempting to process payments that require currency conversion.
MER-PAY-2003	Exchange quote <id> for payment <id> has status ACCEPTED so cannot be accepted	An error is given when attempting to modify a quote that has already been finalised. Once a quote is in a final state, it cannot be changed.
MER-PAY-2004	Payment has expired	An error occurs when attempting to process a payment that has exceeded its expiration time. Expired payments cannot be processed and need to be recreated.
MER-PAY-2005	Instruction validation failed message	The payment instruction data is invalid. This includes validation failures for payment addresses, amounts, or other instruction-specific parameters.
MER-PAY-2006	Merchant not found	An error occurs when the Merchant ID provided in the payment request cannot be found in the account.
MER-PAY-2008	Payment not found	An error occurs when the payment ID cannot be found.
MER-PAY-2009	Invalid request message	Error given for general request validation failures.
MER-PAY-2010	A payment with reference <reference> already exists. Please enter a unique reference.	An error was given when a payment was already created using this reference. All references need to be unique.
MER-PAY-2011	Currency <currency> is disabled	An error occurs when creating a payment with a disabled currency that is not available for trade.
MER-PAY-2012	Insufficient funds	A wallet does not have sufficient funds to complete the requested transaction.
MER-PAY-2014	Exchange quote <id> for payment <id> can no longer be accepted as acceptance has expired	A quote is accepted after it has expired.
MER-PAY-2015	Crypto instruction not found for payment <id>	A required crypto payment instruction cannot be found for the specified payment.
MER-PAY-2016	Merchant not authorised to perform this action	A merchant is not authorised to perform the requested action.
MER-PAY-2017	Cannot cancel payment with external id <id> and status PROCESSING	An attempt is made to cancel a payment and the status is not COMPLETE or PENDING.
MER-PAY-2018	Resource modified by another request	A concurrent modification conflict arises. This happens when multiple requests attempt to modify the same resource simultaneously.
MER-PAY-2019	Currency <currency> not found	The specified currency is not found in the system.
MER-PAY-2024	protocol <protocol> not found for currency <currency>	The specified protocol is not found or not supported for the given currency.
MER-PAY-2025	Please enter your own wallet address, not the address that you paid into originally.	The provided refund address fails validation checks.
MER-PAY-2027	address <address> has failed validation for currency: <currency>, protocol: <protocol> and tag: <tag>	The crypto payout receive address format is invalid.
MER-PAY-2028	We couldn't process your payout request to this address: <address> this time, please try another address.	The crypto payout receiving address is rejected due to risk and compliance reasons.
MER-PAY-2029	Protocol with code <protocol> not found	The specified protocol code is not found in the system.
MER-PAY-2030	Unable to find protocol <protocol> for currency code <currency>	The specified protocol cannot be found for the given currency code.
MER-PAY-2031	Account not enabled for flow: <flow>. Please check your permissions or contact support for more information.	The account is not enabled for the specific payment flow being requested.
MER-PAY-2033	Multiple protocols found for currency <currency> Please specify which one to use: <protocols>.	Multiple protocols are available for a currency, but no specific protocol is selected, rendering automatic selection impossible.
MER-PAY-2035	mass payout data row validation failed	One or more rows in a mass payout file fail validation checks.
MER-PAY-2036	<rows> payments uploaded. This exceeds the maximum number of <max_rows> rows. Please reduce your file to <max_rows> rows.	A mass payout file contains more rows than the system maximum allows.
MER-PAY-2037	Failed to process mass upload file. File name already exists.	Attempting to upload a mass payout file with a filename that already exists.
MER-PAY-2038	Failed to process mass upload file. File is required.	A required mass payout file is not provided.
MER-PAY-2039	Failed to process mass upload file. One of Merchant id or Wallet id fields have to be provided.	A mass payout request is missing both the required merchant ID and wallet ID parameters.
MER-PAY-2040	Failed to process mass upload file. Header is invalid.	The mass payout file contains invalid or missing required headers.
MER-PAY-2041	Deleting mass payout item with status CREATED is not allowed.	An error is given when attempting to delete a mass payout item that is not in a deletable state.
MER-PAY-2042	Updating mass payout item with status <status> is not allowed.	An error is given when attempting to edit a mass payout item that is not in an editable state.
MER-PAY-2043	One of merchantId or walletId properties have to be provided, both are missing	A request requires a merchant ID or a wallet ID, but neither is provided.
MER-PAY-2044	network <network> not found	The specified blockchain network is not valid or supported.
MER-PAY-2045	Payout details currency <currency> and network <network> mismatch from previously provided currency <currency> and network <network>	The payout details do not match the details previously provided for the estimate.
MER-PAY-2046	protocol not found for currency <currency> and network <network>	The specified protocol and network combination is not valid or supported.
MER-PAY-2047	Estimate cannot be modified. Payment with uuid <uuid> already created for estimate <estimate id>.	An error is given when attempting to accept an estimate that already has an associated payment.
MER-PAY-2048	Failed to process mass upload file. File is empty.	The uploaded mass payout file contains no data rows.
MER-PAY-2049	Recipient address is not associated with a contact. You will assign or add a contact to it on the next step.	The specified contact cannot be found for the given address or criteria.
MER-PAY-2050	Recipient address is associated with more than 1 contact. You'll be asked to choose which contact to use for this transaction.	Multiple matching contacts are found for the provided address.
MER-PAY-2051	Crypto account <crypto account> is not verified. Please verify your crypto account before using it	An error occurs when attempting to use an unverified cryptocurrency account that requires verification.
MER-PAY-2052	This country is unavailable. If you require this region, please reach out to your account manager.	Geographical screening encounters an error or fails due to regional restrictions.
MER-PAY-2053	The payment can not be processed.	Geographical screening determines that the payment cannot be processed due to regional restrictions.
MER-PAY-2054	Payment direction 'IN' is not compatible with flow 'EMBEDDED_CRYPTO'	An error is given when attempting to use an unsupported payment direction with an embedded crypto flow.
MER-PAY-2055	mesh client invalid request message	A request to the mesh client is invalid or malformed.
MER-PAY-2056	Customer not found for reference: <customer reference>	The specified customer cannot be found in the system.
MER-PAY-2057	required header missing	A required HTTP header is missing from the request.
MER-PAY-2058	Cannot confirm/accept payment <uuid> as it has been cancelled	An error is given when attempting to perform operations on a payment that has been cancelled.
MER-PAY-2059	Wallet with ID <walletId> not found	The specified wallet ID does not exist.

---

3000-3999

Network

Code	Message	Description
BVNK-3001	Received Bad Request	The system received a request with invalid parameters or missing required information. Check the request format, parameters, and ensure all required fields are properly filled and formatted correctly.
BVNK-3003	Forbidden → received request with wrong authentication details	Access to the requested resource is denied due to authentication failure. Ensure your API keys, tokens, or credentials are valid, correctly included in the request header, and have the necessary permissions to perform this operation.
BVNK-3040	Transfer not found	The requested transfer could not be located in the system. Verify that the transfer identifier is correct and exists within your account. If you recently initiated the transfer, it may still be processing.
BVNK-3041	Action not allowed for the transfer's current status	The requested action can't be performed on the transfer in its current status, for example accepting a quote that was already accepted or has expired. Retrieve the transfer to check its status before retrying.

Customers

Code	Message	Description
MER-PAY-3003	Resource not found	Error given when a requested static resource or endpoint cannot be found.
MER-PAY-3XXX	Unexpected error - please contact administrator	Error given for unexpected or unhandled exceptions.

---

4001-4999

Wallets

Code	Message	Description
BVNK:LEDGER:4001	Received Bad Request	The system received a request with invalid parameters or missing required information. Check the request format, ensure all required fields are properly filled, and validate that parameter values meet the expected format and constraints.
BVNK:LEDGER:4003	FORBIDDEN! You don't have the necessary permissions to access this resource.	Access to the requested resource is denied due to insufficient permissions. This could be due to missing capabilities when creating a customer wallet, or because the customer has been rejected in the system. Verify your account permissions and customer status before retrying.
BVNK:LEDGER:4004	Wallet creation request with the same idempotency key and account reference exists	A wallet creation request with the same idempotency key and account reference already exists in the system. Idempotency keys must be unique for each new wallet creation. Check your records to find the existing wallet or use a new idempotency key for a new wallet.
BVNK:LEDGER:4005	Wallet creation request with missing data, one of the customer reference and external reference has to be provided	The wallet creation request is missing essential identifying information. Either a customer reference or an external reference must be provided in the request. Review your request data and include at least one of these required reference identifiers.

Customers

Code	Message	Description
MER-PAY-4011	Customer fee wallet not found. Please contact support if you need assistance.	The customer fee wallet has not been set. Configuration error.
MER-PAY-4XXX	Unexpected error - please contact administrator	Error given for unexpected or unhandled exceptions.

Customer onboarding

Returned by the Customers API v.2 endpoints (/platform/v2/customers) and the customer agreements endpoints (/platform/v2/agreements).

Code	HTTP status	Message	Description
bvnk:onboarding-accounts:4001	400	JWT is missing the bvnk:accountId claim — cannot determine the caller's account id	BVNK can't identify your account from the request credentials. Check that the request is authenticated with valid API credentials for your account.
bvnk:onboarding-accounts:4002	400	at least one document is required at most 3 documents per request; got <n> metadata count (<n>) must match file count (<m>)	The multipart document upload is malformed. Send 1 to 3 files per request, with one metadata entry for each file, in the same order as the files.
bvnk:onboarding-accounts:4004	400	customer update is only allowed while status is INFO_REQUIRED (current: <status>)	An Update customer request was sent while the customer wasn't in the INFO_REQUIRED status. Retrying won't succeed. Retrieve the customer to check its status and requiredActions. The status in the message is an internal status, which can differ from the customer's status value.
bvnk:onboarding-accounts:4005	400	the onboarding request was rejected	BVNK rejected a request to create or update a customer, or a required actions request. details.errors lists the reasons. Fix the listed issues before retrying.
bvnk:onboarding-accounts:4006	400	the associates request was rejected	BVNK rejected a request to create, update, delete, or retrieve an associate. The message can instead state a specific reason: the associate's identity is already verified, the email address is already used by another associate, or the combined ownership exceeds 100%. Correct the associate details and retry.
bvnk:onboarding-accounts:4007	400	the assigned-agreements request was rejected	BVNK rejected a request to retrieve or act on a customer's assigned agreements. Check the agreement IDs and action types, then retry.
bvnk:onboarding-accounts:4008	400	the identification-documents upload was rejected	BVNK rejected an associate identification document upload. Check the files and metadata against the endpoint requirements, then retry.
bvnk:onboarding-accounts:4009	400	the customer-documents upload was rejected the customer-documents request was rejected	BVNK rejected a customer document upload or a request to retrieve customer documents. Check the files and metadata against the endpoint requirements, then retry.
bvnk:onboarding-accounts:4011	400	agreement cannot be rejected	The agreement can't be declined because its declinable value is false. Send a REJECT action only for agreements where declinable is true.
bvnk:onboarding-accounts:4014	400	customer inputs do not match the inputs used during agreement evaluation	The customer details in a create or update request differ from those used to evaluate the customer's agreements. Send the same values that you used in the Create customer agreements request.
bvnk:onboarding-accounts:4015	400	agreements for reference <ref> have not been signed yet	A Create customer request used a reference whose agreements aren't signed yet. Create the customer after all agreements for this reference are accepted.
bvnk:onboarding-accounts:4016	400	customer request validation failed	The request failed business validation rules. details.errors maps each field path to a message. Fix the listed fields and retry.
bvnk:onboarding-accounts:4017	400	this customer is read-only via this API — use the legacy customers API to make changes	The customer was onboarded with Customers API v.1 and can't be changed with Customers API v.2. Use the Customers API v.1 endpoints to change this customer.
bvnk:onboarding-accounts:4018	400	Customer cannot be onboarded under the assigned legal entity.	The BVNK legal entity assigned to your account can't onboard this customer. Contact your account manager.
bvnk:onboarding-accounts:4019	400	request type does not match the existing onboarding for this reference	The type, useCase, or model in the request differs from the value sent in the Create customer agreements request for this reference. The message names the field that differs. Send the same value as in the agreements request.
bvnk:onboarding-accounts:4021	400	update body must match the customer's kind: expected an 'individual' body	The Update customer body doesn't match the customer type. The message names the expected type, individual or company. Send the company object for a company customer, or the individual object for an individual customer.
bvnk:onboarding-accounts:4022	400	countryCode is required for each individual identity document	An individual customer's identity document was uploaded without countryCode. In each metadata entry, set countryCode to the document's issuing country.
bvnk:onboarding-accounts:4023	400	customer documents and associates cannot be submitted until the agreement is signed (current: <status>)	Documents or associates were submitted while the customer was in the AGREEMENTS_PENDING status, before its agreements were signed. Submit them after the agreements are accepted. The message currently shows the internal status AGREEMENT_CREATED instead of AGREEMENTS_PENDING.
bvnk:onboarding-accounts:4024	400	Idempotency-Key header must match ^[A-Za-z0-9_\-]{1,128}$	The Idempotency-Key header has an invalid format. Use 1 to 128 letters, digits, underscores, or hyphens.
bvnk:onboarding-accounts:4031	403	your account is not permitted to create this customer type — please contact support	Your account isn't enabled for this customer type. Contact support or your account manager to request access.
bvnk:onboarding-accounts:4033	403	your credentials are not permitted to perform this onboarding action	Your API credentials aren't permitted to perform this action. Check that you're using the correct credentials and that they have the required permissions.
bvnk:onboarding-accounts:4040	404	customer not found: id=<uuid>	The customer ID doesn't exist or belongs to another account. Check the customer ID.
bvnk:onboarding-accounts:4041	404	associate not found	The associate ID doesn't exist or doesn't belong to this customer.
bvnk:onboarding-accounts:4042	404	assigned agreement not found	The agreement ID doesn't exist. This code can also appear in the error field of individual results in a Bulk respond to customer agreements response.
bvnk:onboarding-accounts:4043	404	customer document not found	The document ID doesn't exist.
bvnk:onboarding-accounts:4044	404	agreement working set or entry not found for the given reference	No agreement exists for the reference or agreement ID in a customer agreements request. Check the value, and make sure you created the customer agreements first.
bvnk:onboarding-accounts:4090	409	idempotency key reused with a different request body — replay must use the original payload	The Idempotency-Key was already used for a request with a different body. To retry a request, send the original body with the same key. For a new request, use a new key.
bvnk:onboarding-accounts:4091	409	partner external reference already in use within the caller's account	Another customer on your account already uses this reference. Use a unique reference for each customer.
bvnk:onboarding-accounts:4092	409	customer with this id already exists	A customer with this ID already exists, for example because of concurrent create requests or because the customer was created with Customers API v.1. Retrieve the existing customer instead of creating a new one.
bvnk:onboarding-accounts:4093	409	reference is already bound to a customer on this account	The agreements reference is already linked to a customer on your account. To find that customer, search customers by reference.
bvnk:onboarding-accounts:4097	409	customer is rejected or terminated and cannot be changed (current: <status>)	An associate was added to a customer in the REJECTED or TERMINATED status. These customers can't be changed.
bvnk:onboarding-accounts:4290	429	another request with this idempotency key is currently being processed	A request with the same Idempotency-Key is still being processed. Wait, then retry with the same key and body.

Rules

Code	Message	Description
bvnk:payment:rules:4001	Wallet configuration already exists	A wallet configuration with the specified parameters already exists in the system. This error occurs when attempting to create a duplicate wallet configuration that conflicts with an existing one.
bvnk:payment:rules:4002	Address validation error	The provided wallet address failed validation checks. This error indicates that the address format is invalid, doesn't match the expected format for the specified network, or contains invalid characters.
bvnk:payment:rules:4003	Invalid currency	The specified currency code is not recognized or supported by the system. Ensure you're using a valid currency identifier that matches the supported currencies for your account.
bvnk:payment:rules:4004	Unsupported network	The blockchain network specified in the request is not supported by the payment rules system. Check the list of supported networks and use a valid network identifier.
bvnk:payment:rules:4005	Invalid party details	The party details provided in the request contain invalid or missing information. This includes issues with party identification, contact information, or other required party-specific data.
bvnk:payment:rules:4006	Data integrity violation	A data integrity constraint has been violated. This error occurs when the provided data conflicts with existing database constraints or business rules that ensure data consistency.
bvnk:payment:rules:4007	Invalid fee type	The fee type specified in the request is not valid or supported. Check the documentation for valid fee type values and ensure you're using the correct fee structure for your configuration.
bvnk:payment:rules:4008	Invalid destination type	The destination type provided is invalid or not supported for the current operation. Verify that you're using a supported destination type for your wallet configuration.
bvnk:payment:rules:4016	Invalid request format	The request format is malformed or contains invalid structure. This error indicates issues with JSON formatting, missing required fields, or incorrect data types in the request payload.
bvnk:payment:rules:4009	Wallet not found	The specified wallet could not be found in the system. Verify that the wallet ID or identifier exists and that you have the necessary permissions to access it.
bvnk:payment:rules:4010	Wallet configuration not found	The requested wallet configuration does not exist. This error occurs when trying to access, modify, or delete a wallet configuration that is not present in the system.
bvnk:payment:rules:4011	Wallet configuration already active	The wallet configuration is already in an active state and cannot be modified or activated again. Check the current status of the configuration before attempting to change it.
bvnk:payment:rules:4012	Currency mismatch	There is a mismatch between the expected currency and the provided currency. Ensure that all currency references in your request are consistent and match the wallet's configured currency.
bvnk:payment:rules:4013	Wallet status validation error	The wallet status validation failed. This error occurs when the current wallet status doesn't allow the requested operation or when the wallet is in an invalid state for the action being performed.
bvnk:payment:rules:4014	Wallet configuration state error	The wallet configuration is in an invalid state for the requested operation. This may occur when trying to perform actions on configurations that are pending, disabled, or in transition states.
bvnk:payment:rules:4015	Invalid customer fee configuration	The customer fee configuration contains invalid parameters or values. Check that fee amounts, percentages, and fee structure parameters are within acceptable ranges and properly formatted.

5000-5999

Wallets

Code	Message	Description
BVNK:LEDGER:5001	Wallet not found	The requested wallet could not be located in the system. Verify that the wallet identifier is correct and exists within your account.
BVNK:LEDGER:5050	Wallet balance not found	The system could not retrieve balance information for the specified wallet. Ensure the wallet exists and has been properly initialized with a balance.
BVNK:LEDGER:5040	Bad Request	The request contained invalid data, malformed parameters, or violated validation constraints. Review your request format and ensure all required fields contain valid data.
BVNK:LEDGER:5051	Wallet creation failed	The wallet creation process failed to complete successfully. This could be due to system constraints, validation issues, or conflicts with existing data. Check the request details and try again with valid parameters.

Customers

Code	Message	Description
MER-PAY-5001	The requested wallet could not be located in the system.	Verify that the wallet identifier is correct and exists within your account.
MER-PAY-5050	The system could not retrieve balance information for the specified wallet.	Ensure the wallet exists and has been properly initialized with a balance.
MER-PAY-5040	The request contained invalid data, malformed parameters, or violated validation constraints.	Review your request format and ensure all required fields contain valid data.
MER-PAY-5051	The wallet creation process failed to complete successfully. This could be due to system constraints, validation issues, or conflicts with existing data.	Check the request details and try again with valid parameters.

Customer onboarding

Returned by the customer agreements endpoints (/platform/v2/agreements).

Code	HTTP status	Message	Description
bvnk:onboarding-accounts:5021	502	Unexpected error - please contact administrator	A customer agreements request failed for a reason not covered by other codes. Contact support and include the traceId from the response.

Rules

Code	Message	Description
bvnk:payment:rules:5001	Feature not implemented	The requested feature or functionality is not yet implemented in the current version of the payment rules system. This feature may be available in future releases.
bvnk:payment:rules:5003	Wallet validation error	Wallet validation services are currently unavailable. This error indicates a temporary issue with external validation services or network connectivity problems affecting wallet verification.
bvnk:payment:rules:5004	Internal error	An unexpected internal server error occurred while processing the request. This indicates a system-level issue that should be reported to technical support for investigation.