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

# 错误码

<Note>
  * HTTP 状态码一般为 **200**，通过响应体 `code` 判断业务成败；`code = 0` 表示成功，非 0 为失败。
  * **多语言**：请求头 `Language` 控制中英文（如 `zh_CN` / `en_US`）。
  * 参数类错误 **1004、2007～2010、4010** 等会在描述前/后附带 **snake\_case 字段名**。
</Note>

## 错误码分段

| code | 中文描述                  |
| ---- | --------------------- |
| 0    | 成功                    |
| 1xxx | 公共异常、权限异常、鉴权异常、PCI 相关 |
| 2xxx | 会员/持卡人相关异常            |
| 3xxx | 账户、划转相关异常             |
| 4xxx | 卡、卡交易、卡隐私相关异常         |

## 9.1 公共 / 鉴权 / PCI（1xxx）

| code | 中文描述                       |
| ---- | -------------------------- |
| 1001 | 系统开小差了                     |
| 1002 | Api-Key 不能为空               |
| 1003 | IP 地址不正确                   |
| 1004 | 请求参数不合法                    |
| 1005 | 时间戳已失效                     |
| 1006 | Access-Token 不能为空          |
| 1007 | Access-Token 已失效           |
| 1008 | Api-Key 不存在                |
| 1009 | 操作频繁，请稍后重试                 |
| 1010 | Api-Key 未启用                |
| 1011 | Api-Key 已过期                |
| 1012 | 商户对接模式不支持                  |
| 1013 | 未开通 PCI 敏感卡展示能力            |
| 1014 | Client-Access-Token 无效或已使用 |
| 1015 | 父页 Origin 不在报备白名单          |
| 1016 | 请求 Origin 与托管配置不一致         |
| 1017 | 请求重放或 nonce 已使用            |
| 1018 | Sec-Fetch 校验未通过            |
| 1019 | 结束时间不能小于开始时间               |
| 1020 | 查询时间间隔超过限制阈值               |
| 1021 | 商户不存在                      |
| 1022 | 商户状态异常，请联系管理员              |

## 9.2 持卡人（2xxx）

| code | 中文描述                             |
| ---- | -------------------------------- |
| 2001 | 持卡人已存在                           |
| 2002 | 持卡人不存在                           |
| 2003 | 持卡人已认证成功                         |
| 2004 | 持卡人存在进行中的认证                      |
| 2005 | 持卡人认证信息未通过                       |
| 2006 | 持卡人 KYC 信息获取失败                   |
| 2007 | 请使用英文字母、数字、空格或常用地址符号（如 - / #）填写。 |
| 2008 | 仅支持使用英文填写                        |
| 2009 | 国家不支持                            |
| 2010 | 您填写的邮编与所选地址（州 / 省、城市）不匹配         |
| 2011 | 持卡人对应唯一编码不一致                     |

## 9.3 账户 / 划转（3xxx）

| code | 中文描述         |
| ---- | ------------ |
| 3001 | 商户不支持该币种     |
| 3002 | 持卡人账户余额不足    |
| 3003 | 币种主链不匹配      |
| 3004 | 划转流水号已存在     |
| 3005 | 划转金额格式或精度不合法 |
| 3006 | 划转类型不合法      |
| 3007 | 商户账户余额不足     |
| 3008 | 账户余额不足       |

## 9.4 卡 / 消费 / PIN / 隐私（4xxx）

| code | 中文描述                                                      |
| ---- | --------------------------------------------------------- |
| 4001 | 卡 Bin 不可用                                                 |
| 4002 | 卡套餐不存在                                                    |
| 4003 | 商户卡唯一号已存在                                                 |
| 4004 | 卡不存在                                                      |
| 4005 | 当前卡状态不允许此操作                                               |
| 4006 | 开卡数量已达上限                                                  |
| 4007 | 卡商操作失败                                                    |
| 4008 | 实体卡激活请使用商户 App 完成                                         |
| 4009 | 卡消费记录不存在                                                  |
| 4010 | 实体卡账单地址信息不能为空                                             |
| 4011 | 当前申请卡不支持此国家                                               |
| 4012 | 卡信息不存在                                                    |
| 4013 | 卡信息状态不支持                                                  |
| 4014 | 当前卡不支持激活                                                  |
| 4015 | PIN 码解密失败，请检查加密方式与密钥                                      |
| 4016 | PIN 码格式不正确，须为 6 位数字，且不可含三位相同或连续数字（如 111111、123456、654321） |
| 4017 | 该卡不是实体卡，不支持设置 PIN 码                                       |
| 4018 | 未找到可用的 API 凭证                                             |
| 4019 | CVV 解密失败，请检查加密方式与密钥                                       |