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

# 卡申请错误码

> 汇总申请虚拟卡、虚拟卡转实体卡和换卡时可能返回的错误码，并给出重试、补件和用户提示建议。

无论卡订单是在环境校验、用户信息校验、KYC 审核还是卡组织开卡环节失败，您都可以通过 `errorCode` 判断应修改参数后重试、引导用户补件，还是联系客服处理。DCS 为申请虚拟卡、虚拟卡转实体卡和换卡统一返回一套稳定的 `errorCode`，供接入机构在自己的产品中使用。

### 错误码出现在哪里

当卡订单的 `status` 流转为 `FAILED` 时，订单响应中会带上一对字段，描述本次失败的原因：

| 字段            | 类型     | 说明                                  |
| ------------- | ------ | ----------------------------------- |
| `errorCode`   | String | DCS 统一返回的失败原因码，取值见下方各表              |
| `errorReason` | String | 与 `errorCode` 对应的可读文案，可能为面向终端用户的提示语 |

当卡订单 `status=FAILED` 时，`data` 中 `cardId` 为空、`errorCode`/`errorReason` 才有值；例如 `errorCode=INVALID_POA` 属可补件场景，对应 `needExtraInfo=true`（详见下文「补件提示」）。`data` 字段定义见 [开卡 / 卡订单](./card-issuing)。

<Note>
  完整响应结构字段（如 `code`/`message`/`messageDetail`/`data`）的说明见 [开卡 / 卡订单](./card-issuing)；本页聚焦 `errorCode`/`errorReason` 两个字段。
</Note>

这对字段在以下两处出现，**取值一致**，接入机构按任一渠道解析即可：

* **查询卡订单详情**（主动获取）：见 [开卡 / 卡订单](./card-issuing)，当 `status=FAILED` 时响应携带 `errorCode` / `errorReason`。
* **CARD\_ORDER Webhook**（被动接收）：DCS 在卡订单状态变化时推送通知，`data` 中同样携带 `errorCode` / `errorReason`，结构见 [Webhook 事件与数据结构](../webhooks/events-and-schema)。

> **DCS 负责转换错误码**：您无需处理底层 KYC 服务商（如 Sumsub）或卡组织的原始失败码，只需使用下表中的 `errorCode`。如新增取值，DCS 会提前通知接入机构。

### 卡订单状态与失败原因的关系

`status` 的取值**随卡订单类型（`type`）不同**。只有走到 `FAILED` 才会携带失败原因；非终态（如 `PENDING`）不应解析为失败：

| `type`                         | 终态/中间态序列                                                                            | `FAILED` 何时出现                   |
| ------------------------------ | ----------------------------------------------------------------------------------- | ------------------------------- |
| `VIRTUAL`（申请虚拟卡）               | `PENDING → CUSTOMER_PASS → KYC_PASS → CHANNEL_CUSTOMER_PASS → COMPLETED` / `FAILED` | 任一阶段不通过即流转 `FAILED`，最常见为 KYC 阶段 |
| `VIRTUAL_TO_PHYSICAL`（虚拟卡转实体卡） | `PENDING → PHYSICAL_SETTING_COMPLETED → COMPLETED` / `FAILED`                       | 制卡或卡处理环节失败时                     |
| `REPLACEMENT`（换卡）              | `PENDING → COMPLETED` / `FAILED`                                                    | 换卡环节失败时                         |

> `status` 序列与 `COMPLETED` 成功语义详见 [Webhook 事件与数据结构](../webhooks/events-and-schema)。`COMPLETED` 即开卡成功，此时 `cardId` 才有值。

***

## 申请虚拟卡错误码（`type=VIRTUAL`）

申请虚拟卡的失败码分两类：**接入侧/环境类**（接入机构改参数或核对后即可重提交）与 **KYC 拒绝类**（占绝大多数，由底层 KYC 审核产生）。

### 接入侧 / 环境类

这类码与 KYC 无关，多为请求参数或幂等冲突，**接入机构自己即可修复**：

| `errorCode`               | 描述           | 可否重试 | 接入机构怎么办                            | 能否补件 |
| ------------------------- | ------------ | :--: | ---------------------------------- | :--: |
| `OPERATION_NOT_SUPPORT`   | 操作不支持（如重复申请） |   ❌  | 核对是否对同一用户/订单重复发起；按业务去重，勿循环重试       |   否  |
| `EMAIL_ALREADY_EXISTS`    | 邮箱已存在        |  ⚠️  | 该邮箱已注册过用户；改用已存在的 `customerId` 或换邮箱 |   否  |
| `EMAIL_INVALID`           | 邮箱无效         |  ⚠️  | 引导用户更换邮箱后重提交                       |   否  |
| `PHONE_ALREADY_EXISTS`    | 手机号已存在       |  ⚠️  | 该手机号已注册过用户；复用已存在用户或换号              |   否  |
| `CUSTOMER_REF_NOT_UNIQUE` | 客户引用号不唯一     |   ✅  | 更换全局唯一的 `customerRef` 后重提交         |   否  |
| `CUSTOMER_INFO_INVALID`   | 客户信息无效       |   ✅  | 核对手机号/邮箱等字段格式后重提交                  |   否  |
| `CARD_CREATION_FAILED`    | 卡创建失败        |  ⚠️  | 卡处理方开卡失败；稍后重试，持续失败请联系 DCS          |   否  |

### KYC 拒绝类

申请虚拟卡时绝大多数 `FAILED` 来自 KYC 审核被拒。**这批 `errorCode` 与 [KYC 拒绝码](../kyc/kyc-reject-codes) 页来自同一数据源、取值一致**，该页已按业务类别补充「可否重试 / 用户怎么办 / 能否补件」三列并给出接入建议，请以该页为处理依据，避免在本页重复维护。

下面按业务类别列出会出现在卡订单 `errorCode` 中的 KYC 拒绝码。具体处理方式请参阅对应的 [KYC 拒绝码](../kyc/kyc-reject-codes)类别：

* **证件影像质量（可修复，引导重拍/重传）**：`POOR_IMAGE_CAPTURE_QUALITY`、`DOCUMENT_DAMAGED_OR_UNCLEAR`、`POOR_PHOTO_QUALITY`、`LOW_DOCUMENT_QUALITY`、`DOCUMENT_PAGE_MISSING`、`INCOMPLETE_DOCUMENT_SUBMISSION`、`BACK_SIDE_MISSING`、`FRONT_SIDE_MISSING`、`UNSUPPORTED_DOCUMENT_FORMAT`、`INVALID_UPLOAD_TYPE`、`SCREENSHOT_DETECTED`、`COLORED_COPY_REQUIRED`、`ORIGINAL_DOCUMENT_REQUIRED`
* **证件有效性 / 类型（部分可修复）**：`EXPIRED_DOCUMENT`、`UNSUPPORTED_DOCUMENT_TYPE`、`UNSUITABLE_DOCUMENT_SUBMITTED`、`UNSUPPORTED_OR_INVALID_DOCUMENT_TEMPLATE`、`INVALID_IDENTIFICATION_DOCUMENT`、`DOCUMENT_VALIDATION_FAILED`、`UNSUPPORTED_LANGUAGE`、`UNSUPPORTED_DOCUMENT_LANGUAGE`
* **补充材料 / 信息不完整（可修复，走补件）**：`ADDITIONAL_SUPPORTING_DOCUMENT_REQUIRED`、`MORE_SUPPORTING_DOCUMENTS_REQUIRED`、`INCOMPLETE_APPLICANT_DATA`
* **信息不匹配（可修复，核对资料）**：`INFORMATION_MISMATCH`、`PROFILE_INFORMATION_MISMATCH`、`SUBMITTED_DATA_MISMATCH`、`DATABASE_INFORMATION_MISMATCH`、`ADDRESS_INFORMATION_MISMATCH`、`AGE_MISMATCH`、`INVALID_POA`、`INVALID_PROOF_OF_ADDRESS`、`INVALID_POI`、`INVALID_PROOF_OF_IDENTITY`、`INVALID_PROOF_OF_PAYMENT`
* **人脸 / 活体验证（部分可修复）**：`FACE_VERIFICATION_FAILED`、`LIVENESS_CHECK_FAILED`、`THIRD_PARTY_ASSISTANCE_DETECTED`、`IDENTITY_OWNERSHIP_VALIDATION_FAILED`、`MULTIPLE_PERSONS_DETECTED`
* **合规 / 风控终态（不可重试，给中性提示，勿回显合规原因）**：`NAME_SCREENING_HIT`、`EDD_REJECTED`、`SUSPICIOUS_APPLICATION_BEHAVIOR`、`SECURITY_VALIDATION_FAILED`、`SECURITY_SCREENING_FAILED`、`SCREENING_UNSUCCESSFUL`、`COMPLIANCE_RESTRICTION`、`SUMSUB_BLOCKED`、`BLOCKED`
* **资格 / 地区限制（终态，因合作配置而异）**：`OUT_OF_ELIGIBLE_COUNTRIES`、`REGION_OR_RESIDENCY_RESTRICTION`、`ELIGIBILITY_OR_REGION_RESTRICTION`、`FAIL_TO_MEET_DCS_REQUIREMENT`、`FAIL_TO_MEET_PARTNER_REQUIREMENT`、`ELIGIBILITY_REQUIREMENT_NOT_MET`、`AGE_REQUIREMENT_NOT_MET`、`USA_TAX_RESIDENT`、`INCOME_REQUIREMENT_NOT_MET`、`CREDIT_ASSESSMENT_FAILED`、`UNSUPPORTED_PRODUCT`
* **重复 / 欺诈嫌疑（终态）**：`DUPLICATE_APPLICATION_DETECTED`、`INVALID_OR_DUPLICATE_SUBMISSION`、`REAPPLICATION_PERIOD_NOT_MET`（销卡后冷静期未满，勿引导重复申请）
* **数据校验无法完成 / 数据源问题（视情况，多为系统侧稍后重试）**：`APPLICANT_DATA_VALIDATION_FAILED`、`APPLICANT_DATA_NOT_FOUND`、`VERIFICATION_INCOMPLETE`、`VERIFICATION_CHECK_UNAVAILABLE`、`CONNECTIVITY_OR_SERVICE_ERROR`、`DATA_SOURCE_UNAVAILABLE`、`TIMEOUT`、`OTHER_VALIDATION_ISSUE`
* **Share Token / 复用 KYC（多为可重试）**：`INVALID_SHARE_TOKEN`、`SHARE_TOKEN_FAILED`、`INVALID_VERIFICATION_SESSION`、`VERIFICATION_PROCESSING_TIMEOUT`、`REUSABLE_INCOMPATIBLE_DOCUMENT`、`REUSABLE_KYC_NOT_ENABLED`、`REUSABLE_VERIFICATION_NOT_ELIGIBLE`
* **未在时间窗口内完成提交（`TIMEOUT_*`，可重试）**：`TIMEOUT_INVALID_PROOF_OF_IDENTITY`、`TIMEOUT_INVALID_PROOF_OF_ADDRESS`、`TIMEOUT_DOCUMENT_VALIDATION_FAILED`、`TIMEOUT_DOCUMENT_PAGE_MISSING`、`TIMEOUT_EXPIRED_DOCUMENT`、`TIMEOUT_POOR_PHOTO_QUALITY`、`TIMEOUT_SCREENSHOT_DETECTED`、`TIMEOUT_FACE_VERIFICATION_FAILED`、`TIMEOUT_AGE_REQUIREMENT_NOT_MET`、`TIMEOUT_ELIGIBILITY_OR_REGION_RESTRICTION`、`TIMEOUT_SUMSUB_BLOCKED`
* **其他**：`UNSATISFACTORY_DOCUMENT`、`OTHERS`

<Warning>
  **`TIMEOUT_*` 别按后缀理解**：这一组只表示用户未在时间窗口内完成向 Sumsub 的提交，后缀仅说明超时发生在哪一步，**不代表该项校验真的失败**。请按超时处理——引导用户重新发起并尽快完成，而不是按后缀让用户补对应材料。
</Warning>

> **补件提示**：KYC 因 POA/补充材料被拒时（如 `INVALID_POA`、`ADDITIONAL_SUPPORTING_DOCUMENT_REQUIRED`），卡订单响应/Webhook 的 `needExtraInfo=true` 表示需要补充资料；按 [开卡 / 卡订单](./card-issuing) 的补件路径直接补充，**通常无需重新获取 Sumsub Share Token**。

***

## 虚拟卡转实体卡错误码（`type=VIRTUAL_TO_PHYSICAL`）

| `errorCode`                  | 描述        | 可否重试 | 接入机构怎么办                             | 能否补件 |
| ---------------------------- | --------- | :--: | ----------------------------------- | :--: |
| `VIRTUAL_TO_PHYSICAL_FAILED` | 虚拟卡转实体卡失败 |  ⚠️  | 制卡或卡处理环节失败；核对实体卡寄送信息后重试，持续失败请联系 DCS |   否  |

> 该类型只有一个失败码，不再细分原因。具体失败语义可结合 `errorReason` 文案判断。详见 [实体卡](./physical-card)。

***

## 换卡错误码（`type=REPLACEMENT`）

| `errorCode`               | 描述   | 可否重试 | 接入机构怎么办                           | 能否补件 |
| ------------------------- | ---- | :--: | --------------------------------- | :--: |
| `CARD_REPLACEMENT_FAILED` | 换卡失败 |  ⚠️  | 换卡环节失败；核对原卡状态与换卡原因后重试，持续失败请联系 DCS |   否  |

> 该类型只有一个失败码，不再细分原因。换卡操作详见 [卡管理](./card-management)。

***

### 接入建议

* **以 `errorCode` 为准，不要硬编码 `errorReason` 文案**：`errorReason` 可能随版本调整或多语言化；程序分支请基于 `errorCode`，展示文案可用 `errorReason` 或本表自定义。
* **未知码处理**：本表会随合规策略/卡组织能力增删取值。请为「未在已知列表中的 `errorCode`」预留默认分支（统一按 `OTHERS` 处理 + 上报告警），避免新增码导致前端崩溃。
* **区分非终态与失败**：仅在 `status=FAILED` 时解析失败原因；`PENDING` 等中间态不应判定为失败，否则会误拦正常审核中的订单。
* **终态码不要循环重试**：合规 / 资格 / 重复 / 欺诈类（标 ❌）属终态，重复提交无意义且可能触发风控；统一中性提示并引导联系客服。

<Note>
  表中「可否重试 / 能否补件」为接入参考建议；程序分支请以 `errorCode` + `status=FAILED` 为准，并对未在已知列表中的 `errorCode` 设置默认处理（统一按 `OTHERS` 处理 + 上报告警）。
</Note>

***

## 下一步

* 开卡 / 查卡订单状态、解析 `errorCode`：见 [开卡 / 卡订单](./card-issuing)。
* KYC 拒绝码的完整处理动作（可否重试 / 用户怎么办 / 能否补件）：见 [KYC 拒绝码](../kyc/kyc-reject-codes)。
* 接收 `FAILED` 通知、解析 Webhook `data` 字段：见 [Webhook 事件与数据结构](../webhooks/events-and-schema)。