> ## 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.

# 错误码

> VelaFi API 所有错误码及错误信息的完整参考，按类别组织，帮助您快速诊断并解决集成问题。

所有 VelaFi API 响应均为 JSON 格式。调用成功时返回 HTTP `200`，响应外层结构中 `code` 为 `200`、`msg` 为 `"SUCCESS"`，结果位于 `data` 中：

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

> [!NOTE]
>
> 部分接口（包括[升级限额](https://docs.velafi.com/cn/api-reference/merchant/upgrade-merchant-limit.md)（`POST /v2/upgrade/limits`））在成功时返回 `"code": 0` 和 `"msg": "success"`。请将 HTTP `200` 且 `code` 为 `200` 或 `0` 视为成功。

## 错误响应格式

调用失败时返回非 `200` 的 HTTP 状态码。认证、校验、限流和业务错误均使用 HTTP `400`。响应体包含错误 `code` 和英文 `msg`。错误码均为负数，`30012` 除外。对于大多数错误，相同的错误码也会出现在 `error_code` 响应头中。错误响应体中没有 `data` 字段。

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

错误码。请根据此值或 `error_code` 响应头决定如何处理该错误。

**msg** `string`

错误的英文描述。其中可能包含运行时的值，因此请不要按精确文本进行匹配。

**message** `string`

可选。额外的详细信息，仅在部分错误中出现。

**fields** `object`

可选。字段级别的详细信息，仅在部分错误中出现。

> [!NOTE]
>
> 下表中的错误信息包含 `{0}`、`{1}` 或 `%s` 等占位符。VelaFi 通常会将其替换为引发错误的字段名、值或限制，但部分响应会原样返回占位符（例如 `Parameter {0} is invalid`）。请依据 `code` 而不是 `msg` 进行判断。

## HTTP 状态码

| HTTP 状态码 | 场景 | 响应体 |
| - | - | - |
| `200` | 请求成功。 | 成功响应结构 |
| `400` | 认证、校验、限流和业务错误。 | `{"code": <error code>, "msg": "..."}` |
| `404` | 路径不存在。 | 非 VelaFi 响应结构：`{"timestamp": ..., "status": 404, "error": "Not Found", "message": "", "path": "..."}` |
| `405` | 路径存在，但不接受此 HTTP 方法。 | 与 `404` 结构相同，`"status": 405` |
| `500` | 意外的服务器错误。 | `{"code": -1001, "msg": "Internal error."}` |

> [!WARNING]
>
> 认证失败和限流拒绝不使用 `401`、`403` 或 `429`。令牌缺失、过期或无效时返回 HTTP `400` 及代码 `-1002` 或 `-1022`；超出限流时返回 HTTP `400` 及代码 `-1006`。请检查 `code`，而不仅仅是 HTTP 状态码。

## 结果未知：重试前请先确认

> [!WARNING]
>
> 以下响应无法告诉您请求是否已执行。如果您在调用创建或修改类操作（例如创建或确认订单）时收到这些响应，该操作可能已经完成。重试之前，请针对相关时间段调用[订单列表](https://docs.velafi.com/cn/api-reference/order/retrieve-a-list-of-orders.md)（`GET /v2/orders`）并查找您的 `clientId`。仅当订单不存在时才进行重试。

| 代码 | `msg` | 结果未知的原因 |
| - | - | - |
| `-1001` | `Internal error.` | 处理请求时发生意外错误。部分操作可能已经完成。 |
| `-1006` | `Execution status unknown.` | 对于没有特定 Open API 错误码的任何后端错误（包括后端故障），VelaFi 都会返回此代码。 |
| `-1007` | `Timeout waiting for response from backend server.` | 后端未及时响应，但仍可能已完成该操作。 |
| `30012` | `Network busy, Try again later` | 对同一接口的并发请求过多。该请求仍可能被处理。此响应没有 `error_code` 响应头。 |

`-1006` 并不仅限于结果不确定的情况。在只读接口上的部分无效输入场景中（例如在 `GET /v2/base/fiat/payments` 上使用不支持的通道），以及超出[限流](https://docs.velafi.com/cn/api-reference/overview.md#rate-limits)时，也会返回此代码。对于只读的 `GET` 调用，请检查输入后重试。对于创建或修改类调用，请先按上述方式确认。

***

## 认证与请求错误

这些错误来自令牌生成、令牌校验和请求解析。当您的账户未开通 API 访问权限时，`GET /v2/token/generate` 还会返回 `-5033`（参见下方的 KYC/KYB 错误）。

| 代码 | `msg` | 含义 |
| - | - | - |
| `-1002` | `You are not authorized to execute this request` | 缺少 `X-BH-TOKEN` 请求头。在 `/v2/token/generate` 上表示缺少 `X-BH-APIKEY` 请求头，或其不是有效的 API key 格式。 |
| `-1022` | `Signature for this request is not valid.` | 无法识别 `X-BH-TOKEN` 的值，例如令牌已过期。在 `/v2/token/generate` 上表示 API key 未知或 `signature` 不匹配。请生成新的令牌。 |
| `-1023` | `Please set IP whitelist before using API` | 该 API key 未配置 IP 白名单。`/v2/token/generate` 和大多数其他接口都要求配置白名单。 |
| `-2015` | `Invalid API-key, IP, or permissions for action.` | API key 或其所属账户已被禁用。在 `/v2/token/generate` 上，调用方 IP 不在该密钥的 IP 白名单中时也会返回此代码。 |
| `-2019` | `Request ip is not in the whitelist` | 在需要令牌认证的接口上，调用方 IP 不在该 API key 的 IP 白名单中。 |
| `-1000` | `An unknown error occured while processing the request.` | 由于其他原因无法验证凭证。 |
| `-1005` | `No Permission` | 该 API key 所属的账户类型不允许调用此接口。 |
| `-1004` | `Bad request` | 请求格式错误，例如参数类型错误或 JSON 请求体无法解析。缺少必填查询参数时，`msg` 为 `Missing required parameter '<name>'`。 |
| `-1103` | `An unknown parameter was sent.` | 调用 `/v2/token/generate` 时未携带任何查询参数。 |
| `-1130` | `Data sent for paramter '%s' is not valid.` | 某个字段缺失或未通过校验。`%s` 为字段名。拼写 `paramter` 为 API 实际返回的内容。 |
| `-1189` | `Illegal characters found in parameter, illegal content is '%s'.` | 请求体无法转换为预期的类型。`%s` 为解析器的错误文本。 |

***

## 参数错误

参数错误表示一个或多个请求字段未通过基本校验——类型错误、长度错误、格式错误或重复提交。

| 代码 | `msg` | 含义 |
| - | - | - |
| `-4001` | `Request parameter verification error` | 请求参数校验失败 |
| `-4010` | `Parameter {0} is invalid` | 参数 `{0}` 无效 |
| `-4011` | `Parameter {0} exceeds the limit length of {1}` | 参数 `{0}` 的长度超过 `{1}` |
| `-4012` | `Parameter {0} exceeds the limit quantity of {1}` | 参数 `{0}` 的元素数量超过 `{1}` |
| `-4013` | `The length of parameter {0} must be {1} characters` | 参数 `{0}` 的长度必须为 `{1}` 个字符 |
| `-4014` | `The length of parameter {0} must be {1} letters` | 参数 `{0}` 的长度必须为 `{1}` 个字母 |
| `-4015` | `The length of parameter {0} must be {1} digits` | 参数 `{0}` 的长度必须为 `{1}` 位数字 |
| `-4016` | `The parameter {0} must be {1} at position {2}` | 参数 `{0}` 在第 `{2}` 位必须为 `{1}` |
| `-4021` | `Parameter {0} is not numeric type` | 参数 `{0}` 必须为数字 |
| `-4022` | `Parameter {0} is not alphabetic type` | 参数 `{0}` 必须为字母 |
| `-4023` | `Parameter {0} is not alphanumeric type` | 参数 `{0}` 必须为字母或数字 |
| `-4024` | `Parameter {0} is an invalid ISO 3166-1 code` | 参数 `{0}` 不是有效的 ISO 3166-1 代码 |
| `-4025` | `Parameter {0} is an invalid ISO 3166-2 code` | 参数 `{0}` 不是有效的 ISO 3166-2 代码 |
| `-4026` | `Parameter {0} is an invalid account owner type` | 参数 `{0}` 不是有效的账户持有人类型 |
| `-4040` | 具体原因，例如 `Only POL or SPL20 is supported for network.` | 通用错误。`msg` 描述具体原因 |
| `-5040` | `Invalid value of amount` | 金额值无效 |
| `-1174` | `Repeated submit request.` | 同一请求被重复提交 |

***

## 支付方式错误

当支付方式缺失、配置错误或与所请求的操作或平台不兼容时，会出现支付方式错误。

| 代码 | `msg` | 含义 |
| - | - | - |
| `-4027` | `The payment method doesn't exist` | 支付方式不存在 |
| `-5001` | `Please select automatic payment method` | 请选择自动支付方式 |
| `-5002` | `Payment method has no bank account information` | 该支付方式没有银行账户信息 |
| `-5003` | `Payment method cannot be modified temporarily` | 该支付方式暂时无法修改 |
| `-5004` | `Payment method does not have automatic bank API configured` | 该支付方式未配置自动银行 API |
| `-5014` | `Bank card information matches merchant's card information` | 银行账户信息与商户自身账户相同 |
| `-5017` | `Invalid payment method` | 支付方式无效 |
| `-5018` | `Payment method does not match the platform configuration, please choose again` | 支付方式与平台配置不匹配 |
| `-5048` | `The payment type invalid` | 支付类型无效 |
| `-5053` | `Account already exists` | 账户已存在 |
| `-5054` | `Failed to add a payment method, please go to configuration page to edit and submit it again.` | 无法添加该支付方式 |
| `-2017` | `The email already exists.` | 该邮箱已存在 |
| `-2018` | `Illegal email` | 邮箱地址无效 |

***

## 商户错误

商户错误与商户实体的生命周期和配置相关——包括注册失败、记录缺失以及账户状态问题。

| 代码 | `msg` | 含义 |
| - | - | - |
| `-5005` | `Merchant already exists` | 商户已存在 |
| `-5006` | `Merchant does not exist` | 商户不存在 |
| `-5007` | `Invalid merchant information` | 商户信息无效 |
| `-5015` | `The CUIT does not match with your selected merchant` | CUIT 与所选商户不匹配 |
| `-5038` | `The merchant account not exists` | 商户账户不存在 |
| `-5039` | `The merchant settings not exists` | 商户设置不存在 |
| `-5056` | `Payment information doesn't match merchant configuration.` | 支付信息与商户配置不匹配 |
| `-5059` | `Merchant registration failure.` | 商户注册失败 |
| `-5059` | `Please first pass the Liveness authentication` | 必须先完成活体验证。与上一行共用同一代码 |
| `-5064` | `It has exceeded the current maximum number of merchants that can be created (maximum: {0}).` | 您已达到可创建商户的最大数量（`{0}`） |
| `-5065` | `The merchant channel invalid` | 商户渠道无效 |
| `-5066` | `The merchant's account is currently under verification` | 商户账户正在审核中 |
| `-5067` | `The merchant account certification process has been end` | 商户账户审核流程已结束 |
| `-5069` | `The merchant name already exists` | 商户名称已存在 |
| `-5070` | `The merchant has not activated the automatic mode account for {0}. Please activate it and try again.` | 商户尚未激活 `{0}` 的自动模式账户 |
| `-5071` | `The merchant fiat account is invalid` | 商户法币账户无效 |
| `-5077` | `The Merchant has been disabled.` | 商户已被禁用 |
| `-5083` | `The Merchant has been closed.` | 商户已关闭 |

***

## 法币账户与虚拟账户错误

这些错误与激活和使用商户的法币账户及虚拟账户相关。

| 代码 | `msg` | 含义 |
| - | - | - |
| `-5073` | `The merchant did not pass the KYC verification.` | 商户未通过 KYC 验证 |
| `-5074` | `The merchant fiat account has been activated.` | 法币账户已激活 |
| `-5075` | `The merchant fiat account activation failed.` | 法币账户激活失败 |
| `-5076` | `The Merchant fiat account has been closed.` | 法币账户已关闭 |
| `-5078` | `The Merchant fiat account has been disabled.` | 法币账户已被禁用 |
| `-5079` | `No activation permission for the current fiat account.` | 您没有激活此法币账户的权限 |
| `-5084` | `This fiat currency does not support multiple virtual accounts.` | 该法币不支持多个虚拟账户 |
| `-5085` | `Virtual account is under verification.` | 虚拟账户正在审核中 |
| `-5086` | `Virtual account has been activated.` | 虚拟账户已激活 |
| `-5087` | `Virtual account alias is invalid.` | 虚拟账户别名无效 |
| `-5088` | `Virtual account has been disabled.` | 虚拟账户已被禁用 |
| `-5089` | `Virtual account is closed.` | 虚拟账户已关闭 |
| `-5090` | `The virtual account is invalid.` | 虚拟账户无效 |

***

## 订单错误

订单错误表示由于订单当前状态、金额限制或报价已过期，所请求的订单操作无法完成。

| 代码 | `msg` | 含义 |
| - | - | - |
| `-5008` | `Refund orders cannot be processed` | 退款订单无法处理 |
| `-5009` | `Order is in payment process and cannot perform current operation` | 订单正在支付中，无法执行此操作 |
| `-5010` | `Automated orders cannot be completed manually` | 自动化订单无法手动完成 |
| `-5011` | `Automated orders cannot perform current operation` | 自动化订单不支持此操作 |
| `-5034` | `The order process is over.` | 订单流程已结束 |
| `-5035` | `Orders cannot be filled at present.` | 订单目前无法成交 |
| `-5041` | `Only non-payment or support-documents-dending status can upload supporting documents` | 仅未支付或等待补充材料的订单可以上传证明文件 |
| `-5050` | `This order does not meet the minimum limit requirement (min {0} {1}).` | 订单金额低于最低限额（`{0}` `{1}`） |
| `-5060` | `This order does not meet the maximum limit requirement (max {0} {1}).` | 订单金额高于最高限额（`{0}` `{1}`） |
| `-5200` | `The quotation has expired or is invalid.` | 报价已过期或无效 |
| `-1131` | `Balance insufficient ` | 余额不足。例如，当商户的加密货币余额低于订单数量时，加密货币到法币的订单可能会因此代码失败 |
| `-1173` | `Withdraw address illegal.` | 该加密货币地址对所选网络无效 |

***

## 交易对错误

当所请求的交易对、法币、加密资产或国家组合不受支持或已关闭交易时，会出现交易对错误。

| 代码 | `msg` | 含义 |
| - | - | - |
| `-5019` | `Invalid trading pair` | 交易对无效 |
| `-5020` | `BUY direction is closed` | 该交易对已关闭买入 |
| `-5021` | `SELL direction is closed` | 该交易对已关闭卖出 |
| `-5045` | `Invalid fiat` | 法币无效 |
| `-5047` | `The symbol does not match the payment method.` | 交易对与支付方式不匹配 |
| `-5051` | `Fiat currency in the payment method does not match the order fiat currency` | 支付方式的法币与订单的法币不一致 |
| `-5057` | `The currently selected country and fiat currency are not supported.` | 不支持所选的国家和法币 |
| `-5058` | `The currently selected crypto is not supported.` | 不支持所选的加密货币 |

***

## 风控错误

风控错误表示定价或汇率配置超出了可接受的安全阈值。请联系您的 VelaFi 账户管理员解决配置问题。

| 代码 | `msg` | 含义 |
| - | - | - |
| `-5022` | `Price is below the trade line` | 价格低于允许的交易阈值 |
| `-5023` | `The current coin pair is not supported.` | 该交易对未配置汇率，因此不受支持 |
| `-5024` | `Invalid user rate configuration, please contact the administrator.` | 您的汇率配置无效。请联系 VelaFi |
| `-5025` | `Invalid risk control rate configuration, please contact the administrator.` | 风控汇率配置无效。请联系 VelaFi |
| `-5027` | `Current exchange rate is invalid.` | 当前汇率无效 |

***

## KYC/KYB 错误

KYC/KYB 错误表示用户或商户尚未完成所需的身份或企业验证步骤，或者验证流程已进入终止状态。

| 代码 | `msg` | 含义 |
| - | - | - |
| `-5032` | `Not an OTC whitelist. Please contact the OTC customer service manager if you have any needs.` | 您的账户不在 OTC 白名单中。请联系 VelaFi |
| `-5033` | `You are not yet an API user. Please contact the OTC customer service manager if you have any needs.` | 您的账户未开通 API 访问权限。由 `GET /v2/token/generate` 返回 |
| `-5037` | `You need to upload supporting documents.` | 需要上传证明文件 |
| `-5042` | `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 才能执行此操作 |
| `-5044` | `You need to pass KYC & KYB certification first before you can add this payment method.` | 必须先通过 KYC/KYB 才能添加此支付方式 |
| `-5055` | `KYC & KYB registration failed.` | KYC/KYB 注册失败 |
| `-5061` | `Has exceeded the maximum number of documents that can be uploaded (maximum {0})` | 上传的文件过多（最多 `{0}` 个） |
| `-5062` | `The merchant's KYC is currently under verification` | 商户的 KYC 正在审核中 |
| `-5063` | `The merchant KYC certification process has been end` | 商户的 KYC 流程已结束 |

***

## 合规错误

合规错误涵盖范围广泛的政策和配置限制——包括不支持的银行或国家、超出交易限额以及功能访问限制。

| 代码 | `msg` | 含义 |
| - | - | - |
| `-5012` | `Bank not supported` | 不支持该银行 |
| `-5013` | `Automatic API is not supported in this country` | 该国家不支持自动 API |
| `-5016` | `The fiat currency does not match with the merchant` | 法币与商户不匹配 |
| `-5026` | `There are currently {0} orders under review, please wait patiently for the result before creating new orders.` | 审核中的订单过多（`{0}`）。请等待审核完成后再创建新订单 |
| `-5028` | `Self-service ordering function is temporarily closed, please try again later.` | 自助下单功能暂时关闭 |
| `-5029` | `Order has exceeded user's monthly transaction limit.` | 订单超出月度交易限额 |
| `-5030` | `Order has exceeded user's monthly transaction limit with the merchant.` | 订单超出该商户的月度交易限额 |
| `-5081` | `Order has exceeded user's daily transaction limit with the merchant.` | 订单超出该商户的每日交易限额 |
| `-5031` | `This transaction is temporarily unavailable. If you have any questions, please contact customer service.` | 该交易暂时不可用 |
| `-5036` | `fee config invalid. Please contact the OTC customer service manager if you have any needs.` | 手续费配置无效。请联系 VelaFi |
| `-5046` | `Please try again. If you still have questions, please contact the customer service manager.` | 通用错误。请重试或联系 VelaFi |
| `-5049` | `Invalid config` | 配置无效 |
| `-5052` | `Merchant selection is not available for manual payment methods.` | 手动支付方式不允许选择商户 |
| `-5068` | `You are not a user of the Reliance model and therefore cannot use this function.` | 此功能仅适用于 Reliance 模式账户 |
| `-5072` | `Account type[{0}] doesn’t support the bank code[{1}]` | 账户类型 `{0}` 不支持银行代码 `{1}` |

***

## 订单失败代码

这些代码说明订单在创建后失败的原因。当法币到加密货币或加密货币到法币的订单失败时，[获取订单](https://docs.velafi.com/cn/api-reference/order/retrieve-a-specific-order.md)（`GET /v2/order/detail`）可能会在订单的 `failCode` 字段中返回其中之一，并在 `failReason` 中返回对应的文本。并非每个失败或已取消的订单都有 `failCode`。

| `failCode` | `failReason` | 含义 |
| - | - | - |
| `-7000` | `Bank order creation failed.` | 银行或支付服务商无法创建付款 |
| `-7001` | `Incorrect account number for receiving payment.` | 收款账号不正确 |
| `-7002` | `Order cancelled due to timeout.` | 订单因超时被取消 |
| `-7003` | `Order review rejection.` | 订单审核被拒绝 |
| `-7004` | `Order payment is overdue.` | 订单未按时支付 |
| `-7005` | `Insufficient account balance and time limit exceeded.` | 直至超过时限余额仍然不足 |
| `-7007` | `The receiving bank refused to accept.` | 收款银行拒绝接收该笔付款 |
| `-7100` | 服务商自身的错误文本 | `failReason` 包含银行或支付服务商的错误信息，可能是 JSON 字符串 |


## Related topics

- [API 概览](https://docs.velafi.com/cn/api-reference/overview.md)
- [认证](https://docs.velafi.com/cn/api-reference/authentication.md)
- [激活个人商户账户](https://docs.velafi.com/cn/api-reference/merchant/activate-merchant-account-for-individual.md)
- [激活商户账户](https://docs.velafi.com/cn/docs/guides/activating-merchant-account.md)
- [获取 Woovi 活体检测 URL](https://docs.velafi.com/cn/api-reference/merchant/get-woovi-liveness-url.md)


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