> ## 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.

# 授权拒绝与错误码

> 汇总通用接口错误、授权拒绝和各业务模块的错误码，并给出排查与重试建议。

## 📄 正文

无论您是交易所、钱包还是平台方，都可以依赖一套标准化的错误码体系快速定位问题：DCS 所有 API 响应均采用统一格式，合作伙伴自管模式下的拒绝原因也以稳定的错误码返回，便于您在自有系统中做分支判断与用户引导。作为持牌、自有 BIN 的发卡机构，DCS 在授权、清算、对账各环节均保持一致的错误语义。

本页按场景整理合作伙伴自管接口的错误码，并为每类错误补充「可否重试 / 用户怎么办 / 能否补件」的处理建议，帮助接入机构区分**系统级错误**、**参数与业务校验错误**以及**合作伙伴自管模式下的拒绝**。

***

## 统一响应结构

所有接口（无论成功或失败）都返回同一层 JSON 结构：

```json theme={null}
{
  "code": "DAPI_CARD_ORDER_REF_ALREADY_EXISTS",
  "message": "card order ref already exists",
  "messageDetail": null,
  "data": null
}
```

| 字段              | 类型             | 说明                                                                                                              |
| --------------- | -------------- | --------------------------------------------------------------------------------------------------------------- |
| `code`          | string         | 错误码（成功时通常为成功标识，见下方说明）。失败时为本页枚举的 `DAPI_*` 错误码                                                                    |
| `message`       | string         | 错误的简要英文描述，面向开发者，**不建议直接展示给终端用户**                                                                                |
| `messageDetail` | object \| null | 可选的展示明细对象（含 `message` / `title` / `type` / `icon` / `action` / `linkTitle` / `linkUrl`，均为字符串），仅供前端引导，可能为 `null` |
| `data`          | object \| null | 业务数据；失败时通常为 `null`                                                                                              |

**判断成功与否，请以 `code` 为准**（成功为 `SYS_SUCCESS`，失败为本页枚举的 `DAPI_*` 码），不要依赖 `message` 文案，也不要假定 `messageDetail` 一定非空。

> **关于 `DAPI_` 前缀**：本页这些码出现在**响应结构的 `code`** 字段，一律带 `DAPI_` 前缀。另有两类码**不带**前缀，因为它们出现在业务数据里而非结构：卡订单的 `data.errorCode`（见[卡申请错误码](../cards/card-order-codes)）与 KYC 工单的 `data.errorCode`（见 [KYC 拒绝码](../kyc/kyc-reject-codes)）。做分支判断时请按取值所在的位置选对写法。

<Note>
  `messageDetail` 与 `message` 的分工（失败时 `messageDetail` 是否必填）当前文档暂未明确。
</Note>

***

## 错误码分类

下表按场景整理全部 `DAPI_*` 错误码，并为每类错误给出统一的处理建议；需要特别说明的错误码会单独列出。

### 1. 系统级错误（接入机构无法自行修复）

| ErrorCode                    | Message               | 含义      |
| ---------------------------- | --------------------- | ------- |
| `DAPI_SYSTEM_ERROR`          | System error          | 系统内部错误  |
| `DAPI_OPERATION_NOT_SUPPORT` | operation not support | 不支持当前操作 |
| `DAPI_PERMISSION_DENIED`     | permission denied     | 权限不足    |

* **可否重试**：`DAPI_SYSTEM_ERROR` 可在退避后重试；`DAPI_OPERATION_NOT_SUPPORT` / `DAPI_PERMISSION_DENIED` 重试无意义。
* **用户怎么办**：对终端用户提示「系统繁忙，请稍后再试」。
* **能否补件**：不适用。
* **接入机构**：持续出现请联系 DCS 排查，并核对账号开通的能力范围。

### 2. 鉴权与签名错误

| ErrorCode                        | Message                                 | 含义                     |
| -------------------------------- | --------------------------------------- | ---------------------- |
| `DAPI_API_KEY_EMPTY`             | API Key cannot be empty                 | 缺少 API Key 头           |
| `DAPI_INVALID_API_KEY`           | Api Key is invalid                      | API Key 无效             |
| `DAPI_SECRET_KEY_EMPTY`          | Secret Key cannot be empty              | 缺少 Secret Key          |
| `DAPI_SIGNATURE_ERROR`           | signature error                         | 签名校验不通过                |
| `DAPI_CALCULATE_SIGNATURE_ERROR` | Failed to calculate hmac-sha256         | 服务端计算 HMAC-SHA256 签名失败 |
| `DAPI_TIMESTAMP_EMPTY`           | request timestamp cannot be empty       | 缺少请求时间戳                |
| `DAPI_TIMESTAMP_FORMAT_ERROR`    | incorrectly formatted request timestamp | 时间戳格式错误                |
| `DAPI_TIMESTAMP_EXPIRED`         | request timestamp has expired           | 时间戳过期（防重放）             |
| `DAPI_NONCE_ILLEGAL`             | nonce illegal                           | Nonce 非法（防重放）          |

* **可否重试**：修正鉴权头后可重试；`DAPI_TIMESTAMP_EXPIRED` 需用新时间戳重新签名。
* **用户怎么办**：与终端用户无关，属接入机构服务端配置问题。
* **能否补件**：不适用。
* **接入机构**：逐项核对鉴权请求头与签名规则，参见[前置准备](../../getting-started/first-steps)与[鉴权指南](../../integration-resources/authentication)。

<Note>
  Nonce 取值范围为 `[10000, 99999]`，与请求时间戳共同用于防重放校验；调用方不得复用 Nonce，并应对业务写操作另设幂等键。
</Note>

### 3. 参数与权限校验错误

| ErrorCode                         | Message              | 含义       |
| --------------------------------- | -------------------- | -------- |
| `DAPI_SYS_ILLEGAL_PARAM`          | System illegal param | 参数非法     |
| `DAPI_UPLOAD_BUSINESS_TYPE_ERROR` | Wrong business type  | 上传业务类型错误 |

* **可否重试**：修正参数后可重试。
* **用户怎么办**：不适用（服务端集成问题）。
* **能否补件**：不适用。
* **接入机构**：对照对应接口的参数表修正请求体。

### 4. 用户与企业相关错误

| ErrorCode                                   | Message                             | 含义                  |
| ------------------------------------------- | ----------------------------------- | ------------------- |
| `DAPI_ENTERPRISE_NOT_FOUND`                 | enterprise not found                | 企业不存在               |
| `DAPI_CUSTOMER_NOT_FOUND`                   | customer not found                  | 用户不存在               |
| `DAPI_CHANNEL_CUSTOMER_NOT_FOUND`           | channel customer not found          | 渠道侧用户不存在            |
| `DAPI_CHANNEL_CUSTOMER_CREATE_FAILED`       | channel customer create failed      | 渠道侧用户创建失败           |
| `DAPI_CUSTOMER_EMAIL_OR_PHONE_REQUIRED`     | customer email or phone required    | 邮箱或手机至少填一个          |
| `DAPI_PHONE_INVALID`                        | invalid phone                       | 手机号格式错误             |
| `DAPI_EMAIL_INVALID`                        | invalid email                       | 邮箱无效                |
| `DAPI_EMAIL_ALREADY_EXISTS`                 | email already exists                | 邮箱已存在               |
| `DAPI_PHONE_ALREADY_EXISTS`                 | phone already exists                | 手机号已存在              |
| `DAPI_CUSTOMER_REF_NOT_UNIQUE`              | customerRef not unique              | `customerRef` 幂等键重复 |
| `DAPI_ENTERPRISE_BALANCE_RECORD_NOT_EXISTS` | enterprise balance record not found | 企业余额记录不存在           |

* **可否重试**：格式类（`*_INVALID`）修正后可重试；`*_ALREADY_EXISTS` / `*_NOT_UNIQUE` 属幂等/唯一性冲突，应改用已存在的记录而非重复创建。
* **用户怎么办**：邮箱/手机格式或已被占用时，引导用户更换或确认归属。
* **能否补件**：不适用（属创建阶段校验）。
* **接入机构**：`DAPI_CUSTOMER_REF_NOT_UNIQUE` 多因重复提交，建议改用查询已有用户。

### 5. KYC / 工单 / EDD 错误

| ErrorCode                           | Message                              | 含义             |
| ----------------------------------- | ------------------------------------ | -------------- |
| `DAPI_TICKET_REF_REPEATED`          | ticketRef repeated                   | 工单幂等键重复        |
| `DAPI_EXIST_ONGOING_TICKET_ERROR`   | There is an ongoing work order       | 已存在进行中的工单      |
| `DAPI_CARD_ORDER_KYC_INFO_INVALID`  | kyc info invalid                     | KYC 信息无效       |
| `DAPI_CARD_ORDER_KYC_VERIFY_FAILED` | kyc verify failed                    | KYC 校验未通过      |
| `DAPI_REQUEST_REJECTION_ERROR`      | EDD application rejected             | EDD（加强尽调）申请被拒  |
| `DAPI_TICKET_APPLY_LIMIT_EXCEEDED`  | Ticket application exceeds the limit | KYC 工单申请触发进件频控 |

* **可否重试**：`DAPI_EXIST_ONGOING_TICKET_ERROR` 应等待现有工单结束再发起；`DAPI_TICKET_REF_REPEATED` 改用已有工单；`DAPI_TICKET_APPLY_LIMIT_EXCEEDED` 需退避后重试，**不要立即重发**。
* **用户怎么办**：KYC 不通过时，引导用户根据拒绝原因补充资料（POI/POA）。POA 不通过时无需重新获取 Sumsub Token，直接通过补充接口提交。
* **能否补件**：**可补件**——KYC/EDD 拒绝通常允许用户补充或更新材料后再次提交。
* **接入机构**：KYC 流程与状态机参见 [KYC 流程](../../basic-concepts/compliance-kyc-flow)。

<Warning>
  KYC 拒绝原因通过 KYC 工单的 `data.errorCode` / `errorMessage` 返回，完整对照见 [KYC 拒绝码](../kyc/kyc-reject-codes)。
</Warning>

### 6. 卡订单 / 卡配置错误

| ErrorCode                                                           | Message                                                        | 含义                       |
| ------------------------------------------------------------------- | -------------------------------------------------------------- | ------------------------ |
| `DAPI_CARD_ORDER_REF_ALREADY_EXISTS`                                | card order ref already exists                                  | 卡订单幂等键重复                 |
| `DAPI_CARD_ORDER_NOT_FOUND`                                         | card order not found                                           | 卡订单不存在                   |
| `DAPI_CARD_ORDER_ID_INCORRECT_ERROR`                                | businessId is error, cardOrderId incorrect                     | `cardOrderId` 不正确        |
| `DAPI_CARD_ORDER_PROFILE_NOT_FOUND` / `DAPI_CARD_PROFILE_NOT_FOUND` | card profile not found                                         | 卡配置（Profile/Category）不存在 |
| `DAPI_CARD_ORDER_CUSTOMER_INFO_INVALID`                             | customer info invalid                                          | 卡订单中的用户信息无效              |
| `DAPI_CARD_ORDER_CHANNEL_CUSTOMER_INVALID`                          | channel customer invalid                                       | 渠道用户信息无效                 |
| `DAPI_CARD_ORDER_CHANNEL_CARD_INVALID`                              | channel card invalid                                           | 渠道卡信息无效                  |
| `DAPI_CARD_ORDER_NOT_NEED_EXTRA_INFO`                               | card order does not need extra info                            | 该卡订单无需补充额外信息             |
| `DAPI_CARD_ORDER_VIRTUAL_TO_PHYSICAL_FAILED`                        | virtual to physical failed                                     | 虚拟卡转实体卡失败                |
| `DAPI_CARD_PROFILE_NOT_SUPPORTING_COUNTRY_CODES`                    | Card profile not supporting country codes                      | 卡配置不支持该国家码               |
| `DAPI_CARD_LAYOUT_NOT_FOUND`                                        | card layout not found                                          | 卡面（Layout）不存在            |
| `DAPI_EXIST_NOT_FAILED_REPLACE_CARD_ORDER`                          | There are card replacement orders that are not accepted        | 存在未完结的换卡订单               |
| `DAPI_CARD_APPLY_LIMIT_EXCEEDED`                                    | Card application exceeds the limit                             | 申卡触发进件频控（同一用户短时间内申请过于频繁） |
| `DAPI_REPLACE_CARD_APPLY_LIMIT_EXCEEDED`                            | card replacement application limit exceeded within 24 hours    | 换卡触发 24 小时频控             |
| `DAPI_VIRTUAL_TO_PHYSICAL_APPLY_LIMIT_EXCEEDED`                     | virtual to physical application limit exceeded within 24 hours | 虚拟卡转实体卡触发 24 小时频控        |

* **可否重试**：配置类（Profile/Layout/国家码不支持）需先在 DCS 侧确认配置，修正后重试；`*_REF_ALREADY_EXISTS` 改用已有订单；`DAPI_CARD_APPLY_LIMIT_EXCEEDED` 需退避后重试，**不要立即重发**。
* **用户怎么办**：通常无需用户介入；地区不支持时提示用户该卡种在其所在地暂不可用。
* **能否补件**：不适用。
* **接入机构**：公开开卡接口字段使用 `profileId`（企业余额查询使用同义字段 `cardProfileId`）。当前没有在线查询接口，由 DCS 线下分配；不要在公开接口集成中使用内部别名 `categoryId`。

### 7. 卡管理与卡状态错误

| ErrorCode                                 | Message                                                    | 含义              |
| ----------------------------------------- | ---------------------------------------------------------- | --------------- |
| `DAPI_CARD_NOT_FOUND`                     | card not found                                             | 卡不存在            |
| `DAPI_CARD_ID_INCORRECT_ERROR`            | businessId is error, cardId incorrect                      | `cardId` 不正确    |
| `DAPI_CARD_STATUS_NOT_ACTIVATED`          | card status not activated                                  | 卡未处于已激活状态       |
| `DAPI_CARD_STATUS_NOT_FROZEN`             | card status not frozen                                     | 卡未处于冻结状态        |
| `DAPI_CARD_STATUS_NOT_WAITING_ACTIVE`     | card status not waiting active                             | 卡未处于待激活状态       |
| `DAPI_CARD_ACTIVATION_FAILED`             | card activation failed                                     | 卡激活失败           |
| `DAPI_CARD_NOT_EMBOSSED_ERROR`            | Card not embossed: Activation not allowed before embossing | 实体卡未压印，不能在压印前激活 |
| `DAPI_CARD_PIN_MUST_BE_FOUR_DIGIT_NUMBER` | The pin must be a four-digit number                        | PIN 必须为 4 位数字   |
| `DAPI_CARD_TYPE_NOT_VIRTUAL`              | card type is not virtual                                   | 卡类型不是虚拟卡        |
| `DAPI_CARD_TYPE_NOT_PHYSICAL`             | card type is not physical                                  | 卡类型不是实体卡        |
| `DAPI_ORIGINAL_CARD_STATUS_NOT_ACTIVATED` | original card status not activated                         | 原卡未激活（换卡场景）     |
| `DAPI_ORIGINAL_CARD_NOT_FOUND`            | original card not found                                    | 原卡不存在（换卡场景）     |

* **可否重试**：状态不匹配类错误需先把卡流转到正确状态再操作，盲目重试无效。卡状态机见 [卡管理](../cards/card-management)。
* **用户怎么办**：PIN 格式错误时提示用户重新输入 4 位数字；待激活卡需用户先激活。
* **能否补件**：不适用。
* **接入机构**：冻结/解冻同走一个接口 `POST /open-api/card/v1/freeze`，用布尔参数 `freeze` 区分（`true`=冻结，`false`=解冻）；操作前请先确认当前卡状态。

### 8. 引导页错误

| ErrorCode                                 | Message                           | 含义                     |
| ----------------------------------------- | --------------------------------- | ---------------------- |
| `DAPI_GUIDANCE_LINK_TYPE_INVALID`         | guidance link type invalid        | 引导链接类型无效               |
| `DAPI_GUIDANCE_LINK_PRE_VERIFIED_INVALID` | guidance link preVerified invalid | 引导链接的 preVerified 取值无效 |

* **可否重试**：修正引导页参数后可重试。
* **用户怎么办**：不适用（属接入机构生成链接时的参数问题）。
* **能否补件**：不适用。

***

## 合作伙伴自管模式下的拒绝（重点）

在合作伙伴自管模式下，**消费额度由接入机构掌握、授权由接入机构实时决策**。当持卡人刷卡时，DCS 把授权请求转发给接入机构的授权回调地址（`auth_url`），由接入机构返回批准或拒绝。授权被拒时，拒绝原因通过 `AUTHORISATION_RESULT` Webhook 与每日授权报告的 `rejectReason` 字段返回，取值一律带 `DAPI_` 前缀（生产示例：`"approveFlag":"D","rejectReason":"DAPI_SYSTEM_ERROR"`）。完整枚举如下：

| `rejectReason`                          | 触发条件                                                     |
| --------------------------------------- | -------------------------------------------------------- |
| `DAPI_CARD_STATUS_NOT_ACTIVATED`        | 授权进入处理时卡状态非 `ACTIVATED`（未激活/冻结/封锁/失效），出账入账均校验            |
| `DAPI_CARD_CONSUME_FROZEN`              | 用户 KYC 因子过期导致消费受限（仅出账校验）                                 |
| `DAPI_CARD_VELOCITY_LIMIT_CHECK_REJECT` | 限额/流控校验不通过                                               |
| `DAPI_AUTH_ENTERPRISE_REJECT`           | 接入机构在授权回调中明确拒绝                                           |
| `DAPI_AUTH_ENTERPRISE_TIMEOUT_REJECT`   | 接入机构授权回调超时无响应                                            |
| `DAPI_AUTH_INTERNAL_REJECT`             | 系统内部拒绝：验签失败/请求失败/返回非法；找不到卡；增量授权或撤销找不到原授权、币种不匹配；冻结/解冻流程异常 |
| `DAPI_AUTH_INSUFFICIENT_FUNDS_REJECT`   | 前序校验通过后，企业账本资金冻结/解冻失败（余额不足）                              |
| `DAPI_SYSTEM_ERROR`                     | 系统异常兜底                                                   |

校验优先级固定为：**卡状态 → KYC 消费限制 → 限额 → 企业回调 → 资金冻结**；多个条件同时命中时，只返回最先命中的那一个。

* **可否重试**：授权类拒绝属单笔交易结果，由持卡人在商户侧重新发起交易，**接入机构不应对同一笔授权请求做服务端重试**。
* **用户怎么办**：`DAPI_AUTH_ENTERPRISE_REJECT` 多因接入机构侧额度不足或风控；请接入机构按自有规则向终端用户说明（如余额不足、超限）。
* **能否补件**：不适用。
* **接入机构**：超时拒绝（`*_TIMEOUT_REJECT`）应排查授权回调的响应时延。生产环境授权同步应答窗口统一为 **2.5 秒**，接入机构必须在该窗口内同步返回。

<Note>
  授权请求/响应字段与签名规则详见[授权回调](./authorization)；`rejectReason` 在报告文件中的字段位置见[授权报告](../reports/authorization-report)。余额不足、超限、MCC 受限等更细分的业务原因由接入机构在自有授权逻辑中判定并记录。
</Note>

***

## 下一步

错误码定位完成后，请回到 [交易流水](./transaction) 理解 Auth / Outstanding / Transaction 三者的关系，或前往 [沙盒模拟](../sandbox/simulating-transactions) 验证授权拒绝在测试环境下的回放。