错误码
统一响应信封与网关/业务错误码表
错误码
统一响应信封
成功与失败均返回 JSON：
{
"code": 200,
"message": "操作成功",
"data": { }
}code = 200：成功- 其它
code：业务或网关错误，结合message处理
分页列表在 data 内含：records / total / current / size / pages。
HTTP 状态与业务码
网关在鉴权失败时可能直接返回 HTTP 状态；业务错误多为 HTTP 200 + 业务 code（以实际响应为准）。
| 段 | 含义 | 建议 |
|---|---|---|
200 | 成功 | — |
401xx | 未认证 / 签名失败 | 检查 Access Key、时钟、签名串 PATH/body |
403xx | 无权限 / IP / 状态不允许 | 开通权限、配白名单、检查卡状态 |
404xx | 资源不存在 | 核对 ID；跨商户统一 404 防枚举 |
409xx | 冲突（幂等键冲突等） | 换幂等键或复用同一 body |
422xx | 业务不可用（余额不足等） | 充值或调整参数 |
429xx | 限流 | 退避重试 |
5xxxx | 服务暂时异常（可重试） | 写接口带同一幂等键重试 |
常见业务码
| code | 说明 |
|---|---|
200 | 操作成功 |
40101 | 未认证或 Access Key 无效 |
40102 | 签名校验失败 |
40103 | 时间戳超出允许窗口 |
40104 | Nonce 重复或无效 |
40301 | 开发者权限未开通 |
40302 | 操作状态不允许（如卡已 CLOSED 销卡） |
40303 | IP 不在白名单 |
40401 | 资源不存在或不属于当前商户 |
40901 | 幂等键冲突（同键不同 body） |
42201 | 余额不足（含自动兑币后仍不足） |
42202 | BIN / 产品不可用或不在目录 |
42203 | 卡余额不足（转出等） |
42901 | 请求过于频繁（含 secure 专用限流） |
40201 | 缺少幂等键 X-Idempotency-Key |
状态枚举（卡片等）
| 值 | 含义 |
|---|---|
ACTIVE | 正常可用 |
FROZEN | 已冻结 |
CLOSED | 已销卡（不可恢复） |
共享池 status：1 正常 · 0 冻结 · 2 已注销。
排查清单
- 签名 PATH 是否含
/v1、是否误带 query - body 哈希是否与实际发送字节一致
- 服务器时间是否同步（NTP）
- 是否已开通 API、IP 是否入白名单
- 写接口是否带幂等键
详见 常见问题 FAQ。
Updated about 2 months ago
Did this page help you?