200，响应外层结构中 code 为 200、msg 为 "SUCCESS"，结果位于 data 中：
{
"code": 200,
"msg": "SUCCESS",
"data": { ... }
}
部分接口（包括升级限额（
POST /v2/upgrade/limits））在成功时返回 "code": 0 和 "msg": "success"。请将 HTTP 200 且 code 为 200 或 0 视为成功。错误响应格式
调用失败时返回非200 的 HTTP 状态码。认证、校验、限流和业务错误均使用 HTTP 400。响应体包含错误 code 和英文 msg。错误码均为负数，30012 除外。对于大多数错误，相同的错误码也会出现在 error_code 响应头中。错误响应体中没有 data 字段。
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
错误码。请根据此值或
error_code 响应头决定如何处理该错误。string
错误的英文描述。其中可能包含运行时的值，因此请不要按精确文本进行匹配。
string
可选。额外的详细信息，仅在部分错误中出现。
object
可选。字段级别的详细信息，仅在部分错误中出现。
下表中的错误信息包含
{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."} |
认证失败和限流拒绝不使用
401、403 或 429。令牌缺失、过期或无效时返回 HTTP 400 及代码 -1002 或 -1022；超出限流时返回 HTTP 400 及代码 -1006。请检查 code，而不仅仅是 HTTP 状态码。结果未知：重试前请先确认
以下响应无法告诉您请求是否已执行。如果您在调用创建或修改类操作（例如创建或确认订单）时收到这些响应，该操作可能已经完成。重试之前，请针对相关时间段调用订单列表（
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 上使用不支持的通道），以及超出限流时，也会返回此代码。对于只读的 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} |
订单失败代码
这些代码说明订单在创建后失败的原因。当法币到加密货币或加密货币到法币的订单失败时，获取订单（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 字符串 |