Error Codes

Every VelaFi API response is JSON. A successful call returns HTTP 200 and an envelope with code set to 200, msg set to "SUCCESS", and the result in data:

{
  "code": 200,
  "msg": "SUCCESS",
  "data": { ... }
}

Some endpoints, including Upgrade Limit (POST /v2/upgrade/limits), return "code": 0 and "msg": "success" on success. Treat HTTP 200 with code 200 or 0 as success.

Error Response Format

A failed call returns a non-200 HTTP status. Authentication, validation, rate-limit, and business errors use HTTP 400. The body has an error code and an English msg. Error codes are negative, except 30012. For most errors, the same code is repeated in the error_code response header. Error bodies have no data field.

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
error_code: -1002

{"code":-1002,"msg":"You are not authorized to execute this request"}

integer

The error code. Use this value, or the error_code header, to decide how to handle the error.

string

An English description of the error. It can contain runtime values, so do not match on the exact text.

string

Optional. Extra detail, present only on some errors.

object

Optional. Field-level detail, present only on some errors.

Messages in the tables below show placeholders such as {0}, {1}, or %s. VelaFi usually replaces them with the field name, value, or limit that caused the error, but some responses return the placeholder as-is (for example Parameter {0} is invalid). Rely on code, not on msg.

HTTP Status Codes

HTTP status	When	Body
`200`	The request succeeded.	Success envelope
`400`	Authentication, validation, rate-limit, and business errors.	`{"code": <error code>, "msg": "..."}`
`404`	The path does not exist.	Not the VelaFi envelope: `{"timestamp": ..., "status": 404, "error": "Not Found", "message": "", "path": "..."}`
`405`	The path exists but does not accept this HTTP method.	Same shape as `404`, with `"status": 405`
`500`	An unexpected server error.	`{"code": -1001, "msg": "Internal error."}`

Authentication failures and rate-limit rejections do not use 401, 403, or 429. A missing, expired, or invalid token returns HTTP 400 with code -1002 or -1022, and exceeding a rate limit returns HTTP 400 with code -1006. Check code, not only the HTTP status.

Outcome Unknown: Check Before You Retry

The responses below do not tell you whether the request was carried out. If you receive one from a call that creates or changes something, such as creating or confirming an order, the operation may have completed. Before retrying, call List Orders (GET /v2/orders) for the relevant time window and look for your clientId. Retry only if the order is not there.

Code	`msg`	Why the outcome is unknown
`-1001`	`Internal error.`	An unexpected error occurred while the request was being processed. Part of the operation may already have completed.
`-1006`	`Execution status unknown.`	VelaFi returns this code for any backend error that has no specific Open API code, including backend failures.
`-1007`	`Timeout waiting for response from backend server.`	The backend did not answer in time. It may still have completed the operation.
`30012`	`Network busy, Try again later`	Too many concurrent requests to the same endpoint. The request may still be processed. This response has no `error_code` header.

-1006 is not limited to uncertain outcomes. It is also returned for some invalid-input cases on read-only endpoints (for example an unsupported corridor on GET /v2/base/fiat/payments) and when you exceed a rate limit. On read-only GET calls, check your input and retry. On calls that create or change something, check first as described above.

Authentication and Request Errors

These errors come from token generation, token checks, and request parsing. GET /v2/token/generate also returns -5033 (see KYC/KYB Errors below) when API access is not enabled for your account.

Code	`msg`	Meaning
`-1002`	`You are not authorized to execute this request`	The `X-BH-TOKEN` header is missing. On `/v2/token/generate`, the `X-BH-APIKEY` header is missing or is not a valid API key format.
`-1022`	`Signature for this request is not valid.`	The `X-BH-TOKEN` value is not recognized, for example because it has expired. On `/v2/token/generate`, the API key is unknown or the `signature` does not match. Generate a new token.
`-1023`	`Please set IP whitelist before using API`	The API key has no IP whitelist. `/v2/token/generate` and most other endpoints require one.
`-2015`	`Invalid API-key, IP, or permissions for action.`	The API key or its account is disabled. On `/v2/token/generate`, also returned when the calling IP is not in the key’s IP whitelist.
`-2019`	`Request ip is not in the whitelist`	On token-authenticated endpoints, the calling IP is not in the API key’s IP whitelist.
`-1000`	`An unknown error occured while processing the request.`	The credentials could not be verified for another reason.
`-1005`	`No Permission`	The API key’s account type is not allowed to call this endpoint.
`-1004`	`Bad request`	The request is malformed, for example a parameter has the wrong type or the JSON body cannot be parsed. When a required query parameter is missing, `msg` is `Missing required parameter '<name>'`.
`-1103`	`An unknown parameter was sent.`	`/v2/token/generate` was called without any query parameters.
`-1130`	`Data sent for paramter '%s' is not valid.`	A field is missing or fails validation. `%s` is the field name. The spelling `paramter` is what the API returns.
`-1189`	`Illegal characters found in parameter, illegal content is '%s'.`	The request body could not be converted to the expected types. `%s` is the parser’s error text.

Parameter Errors

Parameter errors indicate that one or more request fields failed basic validation — wrong type, wrong length, wrong format, or a duplicate submission.

Code	`msg`	Meaning
`-4001`	`Request parameter verification error`	A request parameter failed validation
`-4010`	`Parameter {0} is invalid`	Parameter `{0}` is invalid
`-4011`	`Parameter {0} exceeds the limit length of {1}`	Parameter `{0}` is longer than `{1}`
`-4012`	`Parameter {0} exceeds the limit quantity of {1}`	Parameter `{0}` has more than `{1}` items
`-4013`	`The length of parameter {0} must be {1} characters`	Parameter `{0}` must be `{1}` characters long
`-4014`	`The length of parameter {0} must be {1} letters`	Parameter `{0}` must be `{1}` letters long
`-4015`	`The length of parameter {0} must be {1} digits`	Parameter `{0}` must be `{1}` digits long
`-4016`	`The parameter {0} must be {1} at position {2}`	Parameter `{0}` must have `{1}` at position `{2}`
`-4021`	`Parameter {0} is not numeric type`	Parameter `{0}` must be numeric
`-4022`	`Parameter {0} is not alphabetic type`	Parameter `{0}` must be alphabetic
`-4023`	`Parameter {0} is not alphanumeric type`	Parameter `{0}` must be alphanumeric
`-4024`	`Parameter {0} is an invalid ISO 3166-1 code`	Parameter `{0}` is not a valid ISO 3166-1 code
`-4025`	`Parameter {0} is an invalid ISO 3166-2 code`	Parameter `{0}` is not a valid ISO 3166-2 code
`-4026`	`Parameter {0} is an invalid account owner type`	Parameter `{0}` is not a valid account owner type
`-4040`	The specific reason, for example `Only POL or SPL20 is supported for network.`	General error. `msg` describes the reason
`-5040`	`Invalid value of amount`	An amount value is invalid
`-1174`	`Repeated submit request.`	The same request was submitted repeatedly

Payment Method Errors

Payment method errors occur when a payment method is missing, misconfigured, or incompatible with the requested operation or platform.

Code	`msg`	Meaning
`-4027`	`The payment method doesn't exist`	The payment method does not exist
`-5001`	`Please select automatic payment method`	Select an automatic payment method
`-5002`	`Payment method has no bank account information`	The payment method has no bank account information
`-5003`	`Payment method cannot be modified temporarily`	The payment method cannot be changed right now
`-5004`	`Payment method does not have automatic bank API configured`	The payment method has no automatic bank API configured
`-5014`	`Bank card information matches merchant's card information`	The bank account details match the merchant’s own account
`-5017`	`Invalid payment method`	Invalid payment method
`-5018`	`Payment method does not match the platform configuration, please choose again`	The payment method does not match the platform configuration
`-5048`	`The payment type invalid`	The payment type is invalid
`-5053`	`Account already exists`	The account already exists
`-5054`	`Failed to add a payment method, please go to configuration page to edit and submit it again.`	The payment method could not be added
`-2017`	`The email already exists.`	The email already exists
`-2018`	`Illegal email`	The email address is invalid

Merchant Errors

Merchant errors relate to the lifecycle and configuration of merchant entities — including registration failures, missing records, and account state problems.

Code	`msg`	Meaning
`-5005`	`Merchant already exists`	The merchant already exists
`-5006`	`Merchant does not exist`	The merchant does not exist
`-5007`	`Invalid merchant information`	The merchant information is invalid
`-5015`	`The CUIT does not match with your selected merchant`	The CUIT does not match the selected merchant
`-5038`	`The merchant account not exists`	The merchant account does not exist
`-5039`	`The merchant settings not exists`	The merchant settings do not exist
`-5056`	`Payment information doesn't match merchant configuration.`	The payment information does not match the merchant configuration
`-5059`	`Merchant registration failure.`	Merchant registration failed
`-5059`	`Please first pass the Liveness authentication`	Liveness verification must be completed first. Shares its code with the row above
`-5064`	`It has exceeded the current maximum number of merchants that can be created (maximum: {0}).`	You have reached the maximum number of merchants (`{0}`)
`-5065`	`The merchant channel invalid`	The merchant channel is invalid
`-5066`	`The merchant's account is currently under verification`	The merchant’s account is under verification
`-5067`	`The merchant account certification process has been end`	The merchant account verification process has ended
`-5069`	`The merchant name already exists`	The merchant name already exists
`-5070`	`The merchant has not activated the automatic mode account for {0}. Please activate it and try again.`	The merchant has not activated the automatic-mode account for `{0}`
`-5071`	`The merchant fiat account is invalid`	The merchant fiat account is invalid
`-5077`	`The Merchant has been disabled.`	The merchant has been disabled
`-5083`	`The Merchant has been closed.`	The merchant has been closed

Fiat Account and Virtual Account Errors

These errors relate to activating and using a merchant’s fiat accounts and virtual accounts.

Code	`msg`	Meaning
`-5073`	`The merchant did not pass the KYC verification.`	The merchant has not passed KYC verification
`-5074`	`The merchant fiat account has been activated.`	The fiat account is already activated
`-5075`	`The merchant fiat account activation failed.`	Fiat account activation failed
`-5076`	`The Merchant fiat account has been closed.`	The fiat account has been closed
`-5078`	`The Merchant fiat account has been disabled.`	The fiat account has been disabled
`-5079`	`No activation permission for the current fiat account.`	You do not have permission to activate this fiat account
`-5084`	`This fiat currency does not support multiple virtual accounts.`	This fiat currency does not support multiple virtual accounts
`-5085`	`Virtual account is under verification.`	The virtual account is under verification
`-5086`	`Virtual account has been activated.`	The virtual account is already activated
`-5087`	`Virtual account alias is invalid.`	The virtual account alias is invalid
`-5088`	`Virtual account has been disabled.`	The virtual account has been disabled
`-5089`	`Virtual account is closed.`	The virtual account is closed
`-5090`	`The virtual account is invalid.`	The virtual account is invalid

Order Errors

Order errors indicate that a requested order operation cannot be completed due to the order’s current state, amount limits, or an expired quotation.

Code	`msg`	Meaning
`-5008`	`Refund orders cannot be processed`	Refund orders cannot be processed
`-5009`	`Order is in payment process and cannot perform current operation`	The order is being paid, so this operation is not available
`-5010`	`Automated orders cannot be completed manually`	Automated orders cannot be completed manually
`-5011`	`Automated orders cannot perform current operation`	Automated orders do not support this operation
`-5034`	`The order process is over.`	The order process has ended
`-5035`	`Orders cannot be filled at present.`	The order cannot be filled right now
`-5041`	`Only non-payment or support-documents-dending status can upload supporting documents`	Supporting documents can only be uploaded for unpaid orders or orders waiting for documents
`-5050`	`This order does not meet the minimum limit requirement (min {0} {1}).`	The order is below the minimum amount (`{0}` `{1}`)
`-5060`	`This order does not meet the maximum limit requirement (max {0} {1}).`	The order is above the maximum amount (`{0}` `{1}`)
`-5200`	`The quotation has expired or is invalid.`	The quote has expired or is invalid
`-1131`	`Balance insufficient`	Not enough balance. For example, a crypto-to-fiat order can fail with this code when the merchant’s crypto balance is below the order quantity
`-1173`	`Withdraw address illegal.`	The crypto address is not valid for the chosen network

Trading Pair Errors

Trading pair errors arise when the requested symbol, fiat currency, crypto asset, or country combination is unsupported or closed for trading.

Code	`msg`	Meaning
`-5019`	`Invalid trading pair`	Invalid trading pair
`-5020`	`BUY direction is closed`	Buying is closed for this pair
`-5021`	`SELL direction is closed`	Selling is closed for this pair
`-5045`	`Invalid fiat`	Invalid fiat currency
`-5047`	`The symbol does not match the payment method.`	The pair does not match the payment method
`-5051`	`Fiat currency in the payment method does not match the order fiat currency`	The payment method’s fiat currency differs from the order’s
`-5057`	`The currently selected country and fiat currency are not supported.`	The selected country and fiat currency are not supported
`-5058`	`The currently selected crypto is not supported.`	The selected crypto is not supported

Risk Control Errors

Risk control errors indicate that pricing or rate configuration is outside acceptable safety thresholds. Contact your VelaFi account administrator to resolve configuration issues.

Code	`msg`	Meaning
`-5022`	`Price is below the trade line`	The price is below the allowed trading threshold
`-5023`	`The current coin pair is not supported.`	No rate is configured for this pair, so it is not supported
`-5024`	`Invalid user rate configuration, please contact the administrator.`	Your rate configuration is invalid. Contact VelaFi
`-5025`	`Invalid risk control rate configuration, please contact the administrator.`	The risk-control rate configuration is invalid. Contact VelaFi
`-5027`	`Current exchange rate is invalid.`	The current exchange rate is invalid

KYC/KYB Errors

KYC/KYB errors indicate that a user or merchant has not completed required identity or business verification steps, or that a verification process has reached a terminal state.

Code	`msg`	Meaning
`-5032`	`Not an OTC whitelist. Please contact the OTC customer service manager if you have any needs.`	Your account is not on the OTC whitelist. Contact VelaFi
`-5033`	`You are not yet an API user. Please contact the OTC customer service manager if you have any needs.`	API access is not enabled for your account. Returned by `GET /v2/token/generate`
`-5037`	`You need to upload supporting documents.`	Supporting documents are required
`-5042`	`No supporting documents were uploaded`	No supporting documents were uploaded
`-5043`	`You need to pass KYC & KYB certification first before you can The current operation can be performed.`	KYC/KYB must be passed before this operation
`-5044`	`You need to pass KYC & KYB certification first before you can add this payment method.`	KYC/KYB must be passed before adding this payment method
`-5055`	`KYC & KYB registration failed.`	KYC/KYB registration failed
`-5061`	`Has exceeded the maximum number of documents that can be uploaded (maximum {0})`	Too many documents uploaded (maximum `{0}`)
`-5062`	`The merchant's KYC is currently under verification`	The merchant’s KYC is under review
`-5063`	`The merchant KYC certification process has been end`	The merchant’s KYC process has ended

Compliance Errors

Compliance errors cover a broad range of policy and configuration restrictions — including unsupported banks or countries, transaction limit breaches, and feature-access restrictions.

Code	`msg`	Meaning
`-5012`	`Bank not supported`	The bank is not supported
`-5013`	`Automatic API is not supported in this country`	The automatic API is not supported in this country
`-5016`	`The fiat currency does not match with the merchant`	The fiat currency does not match the merchant
`-5026`	`There are currently {0} orders under review, please wait patiently for the result before creating new orders.`	Too many orders under review (`{0}`). Wait for them to finish before creating more
`-5028`	`Self-service ordering function is temporarily closed, please try again later.`	Self-service ordering is temporarily closed
`-5029`	`Order has exceeded user's monthly transaction limit.`	The order exceeds the monthly transaction limit
`-5030`	`Order has exceeded user's monthly transaction limit with the merchant.`	The order exceeds the monthly transaction limit for this merchant
`-5081`	`Order has exceeded user's daily transaction limit with the merchant.`	The order exceeds the daily transaction limit for this merchant
`-5031`	`This transaction is temporarily unavailable. If you have any questions, please contact customer service.`	The transaction is temporarily unavailable
`-5036`	`fee config invalid. Please contact the OTC customer service manager if you have any needs.`	The fee configuration is invalid. Contact VelaFi
`-5046`	`Please try again. If you still have questions, please contact the customer service manager.`	Generic error. Try again, or contact VelaFi
`-5049`	`Invalid config`	Invalid configuration
`-5052`	`Merchant selection is not available for manual payment methods.`	Manual payment methods do not allow choosing a merchant
`-5068`	`You are not a user of the Reliance model and therefore cannot use this function.`	This function is only available to Reliance-model accounts
`-5072`	`Account type[{0}] doesn’t support the bank code[{1}]`	Account type `{0}` does not support bank code `{1}`

Order Failure Codes

These codes describe why an order failed after it was created. When a fiat-to-crypto or crypto-to-fiat order fails, Get Order (GET /v2/order/detail) may report one of them in the order’s failCode field, with the matching text in failReason. Not every failed or cancelled order has a failCode.

`failCode`	`failReason`	Meaning
`-7000`	`Bank order creation failed.`	The bank or payment provider could not create the payout
`-7001`	`Incorrect account number for receiving payment.`	The receiving account number is incorrect
`-7002`	`Order cancelled due to timeout.`	The order was cancelled because it timed out
`-7003`	`Order review rejection.`	The order was rejected in review
`-7004`	`Order payment is overdue.`	The order was not paid in time
`-7005`	`Insufficient account balance and time limit exceeded.`	The balance stayed insufficient until the time limit passed
`-7007`	`The receiving bank refused to accept.`	The receiving bank refused the payment
`-7100`	The provider’s own error text	`failReason` holds the bank or payment provider’s error message, which can be a JSON string

Get Started

Core Concepts

Guides

Reference

Error Response Format

HTTP Status Codes

Outcome Unknown: Check Before You Retry

Authentication and Request Errors

Parameter Errors

Payment Method Errors

Merchant Errors

Fiat Account and Virtual Account Errors

Order Errors

Trading Pair Errors

Risk Control Errors

KYC/KYB Errors

Compliance Errors

Order Failure Codes

​Error Response Format

​HTTP Status Codes

​Outcome Unknown: Check Before You Retry

​Authentication and Request Errors

​Parameter Errors

​Payment Method Errors

​Merchant Errors

​Fiat Account and Virtual Account Errors

​Order Errors

​Trading Pair Errors

​Risk Control Errors

​KYC/KYB Errors

​Compliance Errors

​Order Failure Codes

Error Response Format

HTTP Status Codes

Outcome Unknown: Check Before You Retry

Authentication and Request Errors

Parameter Errors

Payment Method Errors

Merchant Errors

Fiat Account and Virtual Account Errors

Order Errors

Trading Pair Errors

Risk Control Errors

KYC/KYB Errors

Compliance Errors

Order Failure Codes