Virtual Account OpenAPI 错误码说明

5. 错误响应

5.1 错误响应格式

{
  "code": 10010000,
  "message": "virtual_account parameters error",
  "data": null
}

调用方必须检查响应 Body 中的 code：

code = 0：请求处理成功；

code != 0：请求处理失败，具体原因参见错误码说明。

5.2 错误码说明

HTTP 状态码	业务错误码	错误信息	具体说明	处理建议
400	`10010000`	Invalid parameters	必填参数缺失，或者参数类型、格式、长度、取值范围不符合要求	根据响应 `message` 中的字段名称修改请求参数
400	`10010000`	Invalid virtual account number	`virtual_account` 不是 7～15 位数字字符串	检查号码长度，并删除空格、字母或特殊字符
400	`10010000`	Invalid pagination parameters	`page_number` 小于 1，或者 `page_size` 不在 1～100 之间	修改分页参数后重新请求
400	`10010000`	Invalid request format	请求 Body 不是合法 JSON，或者字段类型不符合要求	检查 JSON 格式、字段类型和 `Content-Type`
400	`30010011`	Missing required merchant field	无法从 Access Token 中获取有效的 Merchant ID	检查 Access Token 对应的商户信息
401	`30010002`	Invalid access token	Access Token 无效、格式错误或已过期	重新获取 Access Token 后重试
401	`10010004`	Invalid signature	请求签名缺失或签名校验失败	检查签名算法、密钥和参与签名的请求参数
403	`10000004`	Permission denied	当前商户没有调用该接口的权限	联系平台开通相应接口权限
403	`30010020`	Invalid merchant status	商户不存在、未通过审核或账户已被冻结	确认商户状态，或者联系平台处理
404	`10090002`	Virtual account not found	VA 不存在、不属于当前商户、VA 类型不匹配或 VA 状态不可用	检查 VA 号码、商户归属和 VA 状态
409	`30010013`	External ID already exists	当前商户已经使用相同的 `external_id` 提交过创建请求	使用原 `external_id` 查询处理结果，不要重复创建
422	`30010014`	Merchant fee not found	商户没有配置 VA 服务费率，或者当前 VA 类型没有匹配的费率	联系平台配置 VA 服务费率
500	`10000000`	System error	平台内部发生未知异常	保存请求信息和发生时间，并联系平台技术支持
500	`10090000`	Failed to create virtual account	平台或支付渠道未能成功创建 VA	稍后查询创建结果；确认失败后再决定是否重试
500	`-1`	Internal runtime error	系统发生未映射到具体业务错误码的运行时异常	保存请求信息和发生时间，并联系平台技术支持
502	`下游返回码`	Payment channel error	银行或支付渠道返回业务错误，具体 Code 和信息由渠道决定	根据响应 `message` 处理，未知错误请联系平台
503	`10000001`	Service maintenance	VA 服务正在维护或暂时不可用	根据平台通知或 `Retry-After` 稍后重试

10010000 是统一参数错误码。具体是哪个参数错误，需要结合响应中的 message 判断。

当前代码已经定义 10010004 签名错误码，但 VA 接口的应用层 HMAC 校验暂未启用。如果 API 网关启用了签名校验，仍可能返回该错误。

当前创建 VA 的部分下游异常会在 Service 内部被捕获，接口可能返回 code = 0，但 data.status 为失败且 data.virtual_account 为空。调用方不能只检查 code。

6. 错误处理建议

6.1 不应直接重试

以下错误必须先修改参数、凭证或商户配置：

10010000：修改请求参数；

10010004：修正请求签名；

10000004：申请接口权限；

30010002：重新获取 Access Token；

30010011：检查 Access Token 中的商户信息；

30010013：查询原请求结果，不要重复创建；

30010014：联系平台配置 VA 服务费率；

30010020：确认商户审核或冻结状态；

10090002：检查 VA 号码和商户归属。

6.2 可以谨慎重试

以下错误可以采用指数退避策略重试：

10000000：系统内部错误；

10000001：服务维护；

10090000：VA 创建失败；

HTTP 429：请求频率超过限制；

HTTP 500：平台内部错误；

HTTP 502：支付渠道暂时不可用；

HTTP 503：服务暂时不可用。

建议重试策略：

第一次失败后等待 1 秒；

第二次失败后等待 2 秒；

第三次失败后等待 4 秒；

最多重试 3 次；

如果响应包含 Retry-After，优先按照该响应头指定的时间重试。

6.3 创建 VA 的特殊判断

创建 VA 后，调用方应依次检查：

code 是否为 0；

data.status 是否为成功；

data.virtual_account 是否非空；

相同 external_id 是否已经存在处理记录。

示例：

7. 注意事项

virtual_account 必须使用字符串类型传递。

virtual_account 必须为 7～15 位纯数字。

建议使用正则表达式 ^[0-9]{7,15}$ 校验 VA 号码。

创建 VA 时必须使用唯一的 external_id。

external_id 应作为创建请求的幂等标识。

不要只根据 HTTP 状态码判断业务结果，必须检查响应中的 code。

创建接口还必须检查 data.status 和 data.virtual_account。

查询不到入账记录时可以返回空列表，不应作为系统错误处理。

金额字段应使用字符串或十进制定点数处理，不能使用浮点数直接计算。

10.

日志中不得记录完整 Access Token、签名密钥或其他敏感凭证。

Virtual Account Error Codes

Virtual Account OpenAPI 错误码说明#

5. 错误响应#

5.1 错误响应格式#

5.2 错误码说明#

6. 错误处理建议#

6.1 不应直接重试#

6.2 可以谨慎重试#

6.3 创建 VA 的特殊判断#

7. 注意事项#