> ## Documentation Index
> Fetch the complete documentation index at: https://docs.velafi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Codes

> Complete reference for all VelaFi API error codes and messages, organized by category to help you diagnose and resolve integration issues quickly.

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`:

```json theme={null}
{
  "code": 200,
  "msg": "SUCCESS",
  "data": { ... }
}
```

> [!NOTE]
>
> Some endpoints, including [Upgrade Limit](https://docs.velafi.com/api-reference/merchant/upgrade-merchant-limit.md) (`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 theme={null}
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"}
```

**code** `integer`

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

**msg** `string`

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

**message** `string`

Optional. Extra detail, present only on some errors.

**fields** `object`

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

> [!NOTE]
>
> 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."}` |

> [!WARNING]
>
> 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

> [!WARNING]
>
> 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](https://docs.velafi.com/api-reference/order/retrieve-a-list-of-orders.md) (`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](https://docs.velafi.com/api-reference/overview.md#rate-limits). 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](https://docs.velafi.com/api-reference/order/retrieve-a-specific-order.md) (`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 |


## Related topics

- [API Overview](https://docs.velafi.com/api-reference/overview.md)
- [Activate an Individual Merchant Account](https://docs.velafi.com/api-reference/merchant/activate-merchant-account-for-individual.md)
- [Activate a Merchant Account](https://docs.velafi.com/docs/guides/activating-merchant-account.md)
- [Get Woovi Liveness URL](https://docs.velafi.com/api-reference/merchant/get-woovi-liveness-url.md)
- [Generate a Token](https://docs.velafi.com/api-reference/generate-token.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.