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

# 错误码

> 查阅 Card Issuance API 返回的错误码、出现位置以及对应的处理方式。

当 Card Issuance API 调用失败时，网关会返回非 2xx 的 HTTP 状态码以及 JSON 错误体。通过本页你可以定位问题原因并恢复调用。

<h2 id="error-response-formats">错误响应格式</h2>

Card Issuance API 使用**两种响应信封**。具体返回哪一种取决于处理请求的 handler。

<Tabs>
  <Tab title="信封 A —— 字符串 code">
    绝大多数卡片与持卡人错误都会返回这种信封。`type` 决定 HTTP 状态码。

    ```json theme={null}
    {
      "type": "card_error",
      "code": "card_not_found",
      "message": "card not found or deactivated"
    }
    ```

    | Field     | 含义                                        |
    | --------- | ----------------------------------------- |
    | `type`    | 高层分类。映射到 HTTP 状态码（见[错误类型](#error-types)）。 |
    | `code`    | 机器可读的字符串标识。用于程序化处理。                       |
    | `message` | 人类可读的描述。可以安全写入日志，但不建议原样展示给终端用户。           |
  </Tab>

  <Tab title="信封 B —— 旧版扁平 400">
    一部分 handler——主要是早于类型化错误系统的老旧卡片操作——会返回一种扁平结构：`code` 是作为字符串的 HTTP 状态码，`message` 承载错误语句。

    ```json theme={null}
    {
      "code": "400",
      "message": "Create card error"
    }
    ```

    | Field     | 含义                                                                      |
    | --------- | ----------------------------------------------------------------------- |
    | `code`    | 作为字符串的 HTTP 状态码（校验/业务错误为 `"400"`，限流请求为 `"429"`）。按 `message` 字段分支做细粒度处理。 |
    | `message` | 人类可读的描述。                                                                |

    <Tip>
      处理响应时，根据是否存在 `type` 字段来判断使用哪种信封。信封 B 永远不带 `type`。
    </Tip>
  </Tab>
</Tabs>

<h2 id="error-types">错误类型</h2>

信封 A 把错误码按 type 分组，每个 type 固定映射到一个 HTTP 状态码。

| `type`                  | HTTP      | 出现场景                                                                     |
| ----------------------- | --------- | ------------------------------------------------------------------------ |
| `invalid_request_error` | 400       | 请求校验失败。                                                                  |
| `card_error`            | 400       | 违反卡资源规则。                                                                 |
| `cardholder_error`      | 400       | 违反持卡人资源规则。                                                               |
| `account_error`         | 400       | 违反账户/产品/余额规则。                                                            |
| `idempotency_error`     | 400       | 幂等键重放或不匹配。                                                               |
| `unauthorized_error`    | 401 / 403 | API 密钥缺失、无效或没有权限。401 时 `code` 为 `unauthorized_error`，403 时为 `forbidden`。 |
| `api_error`             | 500       | 内部服务器错误。可以用相同的 `Idempotency-Key` 安全重试。                                   |

信封 B 不带 `type` 字段；通过 `message` 分支区分具体情况。

<h2 id="common-errors">通用错误</h2>

以下错误可能出现在任何需要鉴权的 endpoint。

<h3 id="envelope-a-string-codes">信封 A（字符串 code）</h3>

| `code`                    | `type`                  | 错误消息                                                                                   | 处理方式                                                                           |
| ------------------------- | ----------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| `invalid_request_error`   | `invalid_request_error` | *（视场景而定——`message` 中会指出字段路径和校验规则）*                                                     | TODO                                                                           |
| `unauthorized_error`      | `unauthorized_error`    | Token expired, IP not allowed, or access token dependencies unavailable                | 通过 **Access Token** 获取新的 Access Token，确认调用方 IP 在白名单内，然后用新的 `x-auth-token` 头重试。 |
| `forbidden`               | `unauthorized_error`    | Returned when the API key lacks permission (currently guards `GET /cards/{id}/secure`) | 联系你的 UQPAY solutions engineer 为 API 密钥开启敏感卡详情权限，然后重试。                          |
| `api_error`               | `api_error`             | *（视场景而定——通用的内部服务器错误）*                                                                  | TODO                                                                           |
| `account_not_found`       | `account_error`         | account not found or deactivated                                                       | 确认你使用的 `client_id` / API 密钥归属于一个生效中的 UQPAY 账户。如果账户是近期创建的，请确认入驻流程已完成。           |
| `sub_account_not_found`   | `account_error`         | sub-account associated with the on-behalf-of not found or deactivated                  | 确认 `on-behalf-of` 头指向你主账户下一个存在且生效的子账户，或不带该头以主账户身份调用。                           |
| `user_not_found`          | `account_error`         | user associated with account not found or deactivated                                  | 确认绑定到 API 密钥的用户仍在生效。如果该用户近期被禁用，请联系你的 UQPAY solutions engineer。                 |
| `request_being_processed` | `idempotency_error`     | request is being processed                                                             | 稍后用相同的 `Idempotency-Key` 重试——原始请求仍在处理中。重试之间不要修改请求体。                            |
| `invalid_key_format`      | `idempotency_error`     | invalid idempotency key format                                                         | 提供一个非空、长度不超过 255 个字符的 `Idempotency-Key` 头（推荐使用 UUID v4）。                       |
| `key_mismatch_account`    | `idempotency_error`     | key does not belong to account                                                         | 该 `Idempotency-Key` 之前被其他账户使用过——请为当前账户生成一个新的 key。                              |
| `key_mismatch_api`        | `idempotency_error`     | api associated with key is not the original                                            | `Idempotency-Key` 只能在首次使用时的同一 endpoint + method 上重用。换 endpoint 请生成新的 key。      |

<h3 id="envelope-b-legacy-flat-400">信封 B（旧版扁平 400）</h3>

| `code` | 错误消息                                         | 处理方式                                                                          |
| ------ | -------------------------------------------- | ----------------------------------------------------------------------------- |
| `400`  | Request parameters invalid                   | 对照 API Reference 中该 endpoint 的 schema，检查每个必填字段是否存在且类型正确。                      |
| `400`  | Params JSON error                            | 请求体 JSON 解析失败——检查是否有尾随逗号、未转义的引号，或缺少 `Content-Type: application/json` 头。       |
| `400`  | Account does not exist.                      | 确认 API 密钥归属于一个生效中的账户，且解析到的账户未被停用。                                             |
| `400`  | An internal error occurred, please try again | 短暂回退后用相同的 `Idempotency-Key` 重试。如果错误持续，联系你的 UQPAY solutions engineer 并附上请求时间戳。 |
| `400`  | Login expired                                | 通过 **Access Token** 获取新的 Access Token，并用新的 `x-auth-token` 重试。                 |
| `429`  | Request is too frequent                      | 按指数退避重试。敏感卡和 PAN Token 类 endpoint 按卡限流——轮询间隔请不要短于几秒。                          |

<h2 id="resource-errors">资源错误</h2>

<h3 id="card-errors">卡片错误</h3>

<Accordion title="相关 endpoint">
  Create Card · List Cards · Update Card · Retrieve Card · Update Card Status · Retrieve Sensitive Card Details · Create PAN Token · Card Recharge · Card Withdraw · Retrieve Card Order · Activate Card · Reset Card PIN · Assign Card
</Accordion>

*信封 A 的 type：`card_error`，以及创建卡片时可能出现的 `account_error`（`product_not_found`、`account_balance_error`）。*

**信封 A**

| `code`                                | 错误消息                                                                                 | 典型接口                                                                | 处理方式                                                                                                           |
| ------------------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `card_not_found`                      | card not found or deactivated                                                        | 任何接收 `{card_id}` 的 endpoint                                         | 确认 `card_id` 存在于你的账户下且未注销。使用 **List Cards** 或 **Retrieve Card** 核对。                                            |
| `operation_not_authorized`            | requested card operation type is not authorized                                      | Create Card                                                         | 你的账户没有发行该卡类型的权限——联系你的 UQPAY solutions engineer 在账户上开启。                                                         |
| `risk_control_not_allowed`            | risk control setting is not allowed                                                  | Create Card                                                         | 移除或调整超出卡产品允许范围的 `risk_controls` 条目。支持的配置见 **[卡产品](/zh/card-issuance/v1.6/guide/card-products)** 能力矩阵。          |
| `currency_not_allowed`                | card currency is not allowed                                                         | Create Card                                                         | 将 `currency` 设置为所选卡产品支持的币种之一。找你的 UQPAY solutions engineer 确认产品配置。                                              |
| `limit_out_of_range`                  | card limit is either less than minimum card limit or greater than maximum card limit | Create Card                                                         | 将 `spending_controls.spending_limit` 设置在该产品配置的最小值与最大值之间。上下限按卡产品设定——联系你的 UQPAY solutions engineer 确认。           |
| `cardholder_quota_exceeded`           | card quota of cardholder exceeds limit                                               | Create Card                                                         | 该持卡人已达到允许的最大活动卡数量。先通过 **Update Card Status** 注销一张已有的卡，再发行新卡，或换一个持卡人。                                           |
| `account_quota_exceeded`              | card quota of account exceeds limit                                                  | Create Card                                                         | 账户级别的卡数量上限已达到。通过 **Update Card Status** 注销未使用的卡，或联系你的 UQPAY solutions engineer 提高配额。                           |
| `insufficient_sub_bin`                | insufficient available cards for sub-bin                                             | Create Card                                                         | 你账户下该卡产品对应的子 BIN 池已无可用卡号。这是库存问题，不是请求问题——请将你的账户 ID 以及目标卡产品 / BIN 提供给 UQPAY OPS，由 OPS 补充库存。在库存补齐之前，相同请求重试也会一直失败。 |
| `card_expired_error`                  | card has expired                                                                     | Reset Card PIN                                                      | 卡已过期——不再允许重置 PIN 码。如有需要，请补发一张新卡。                                                                               |
| `status_not_supported`                | card status or activation status not supported by request                            | Reset Card PIN · Create PAN Token · Retrieve Sensitive Card Details | 执行该操作要求卡处于可用的激活状态。用 **Retrieve Card** 查看 `status`，先激活或解除锁定。                                                    |
| `virtual_card_pin_error`              | virtual cards do not allow pin settings                                              | Reset Card PIN                                                      | 虚拟卡没有 PIN 码——该 endpoint 仅适用于实体卡。                                                                               |
| `auto_cancel_trigger cannot be empty` | *（`code` 字符串即 message——不单独返回 `message`）*                                             | Create Card                                                         | 当卡产品要求时（通常是一次性卡），需要提供 `auto_cancel_trigger`。                                                                   |
| `invalid auto_cancel_trigger`         | *（`code` 字符串即 message）*                                                              | Create Card                                                         | 使用 **Create Card** 文档中列出的合法 `auto_cancel_trigger` 取值之一。                                                        |
| `expiry_at cannot be empty`           | *（`code` 字符串即 message）*                                                              | Create Card                                                         | 当卡产品要求显式指定过期日期时，需要提供 `expiry_at`。                                                                              |
| `invalid expiry_at`                   | *（`code` 字符串即 message）*                                                              | Create Card                                                         | `expiry_at` 必须是 ISO 8601 格式的未来时间戳，且在产品允许的最长有效期内。                                                               |
| `product_not_found`                   | product not found or inactive                                                        | Create Card                                                         | 确认 `card_product_id` 指向一个在你的账户上启用的产品。通过 UQPAY 控制台或联系 solutions engineer 核对。                                    |
| `account_balance_error`               | insufficient balance or currency balance unavailable                                 | Create Card                                                         | 在重试之前，为卡币种对应的发卡账户余额充值。参见 **Fund your issuing balance** 指南。                                                     |
| `card_art_not_available`              | card\_art\_id is not available for this account                                      | Create Card · Update Card · Set Default Card Art                    | 你传入的 `card_art_id` 不在该账户的可用列表中。先调用 **List Card Arts** 查看允许的取值，或省略 `card_art_id` 改用账户的默认卡面。                     |
| `card_art_not_configured`             | card art is not configured                                                           | Create Card · Update Card · List Card Arts                          | 通道没有配置系统默认卡面，发卡账户也没有绑定任何卡面。联系你的 UQPAY solutions engineer 为该通道配置卡面。                                             |
| `card_art_not_supported`              | card\_art\_id is not supported for this product                                      | Create Card · Update Card                                           | 所选卡产品不支持卡面选择。请从请求中省略 `card_art_id`，或改用支持卡面的卡产品。                                                                |

**信封 B**

| `code` | 错误消息                                                                | 典型接口                                                      | 处理方式                                                                                                             |
| ------ | ------------------------------------------------------------------- | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `400`  | Card does not exists                                                | 任何接收 `{card_id}` 的 endpoint                               | 确认 `card_id` 存在于你的账户下。使用 **List Cards** 核对。                                                                      |
| `400`  | card bin not config                                                 | Create Card · Assign Card                                 | 你账户下尚未配置该 BIN，因此无法在该 BIN 上创建或分配卡片。请将你的账户 ID 以及目标 BIN 提供给 UQPAY OPS，由 OPS 配置后即可使用。                                |
| `400`  | card number not exist                                               | Assign Card                                               | 该 `card_number` 不在你账户当前的可用卡池中。请核对：(1) 卡号是 UQPAY 为该账户提供的；(2) 卡号长度正确——不要带空格、不要带前后多余字符、不要少位；(3) 该卡片尚未被分配给其他持卡人。     |
| `400`  | Create card error                                                   | Create Card                                               | 用相同的 `Idempotency-Key` 重试。如果持续失败，对照 **Create Card** 的 schema 检查请求体，并联系你的 UQPAY solutions engineer。               |
| `400`  | Update card error                                                   | Update Card · Activate Card                               | 重试请求。如果仍然失败，通过 **Retrieve Card** 确认卡处于可更新状态，且要修改的字段在该产品下允许修改。                                                    |
| `400`  | Card retrieve error                                                 | Retrieve Card · Retrieve Sensitive Card Details           | 短暂回退后重试。如果卡是近期创建的，请等几秒钟让数据同步。                                                                                    |
| `400`  | Card status is invalid                                              | Update Card Status                                        | 将 `status` 设为卡当前状态允许的取值之一（见 **Card lifecycle** 指南）。例如，已注销的卡无法再切回 active 状态。                                      |
| `400`  | The card is failed.                                                 | Retrieve Card                                             | 卡在发卡方侧制卡失败——既无法查询也无法使用。请补发一张新卡。                                                                                  |
| `400`  | The card is not active.                                             | Update Card · Card Recharge · Card Withdraw               | 在更新、充值或提现之前，先通过 **Activate Card** 激活卡片。                                                                          |
| `400`  | Update reason is too long                                           | Update Card Status                                        | 缩短 `reason` 字段的内容。该字段以有限长度的列存储——请控制在几百个字符以内。                                                                     |
| `400`  | The card has expired                                                | Update Card · Update Card Status · Activate Card          | 卡已超过 `expiry_at`，无法再修改或激活。请补发一张新卡。                                                                               |
| `400`  | Invalid expiry date                                                 | Card Recharge · Card Withdraw                             | 卡已过期——充值和提现被阻断。如持卡人仍需用卡，请补发新卡。                                                                                   |
| `400`  | Card holder not exists or is illegal                                | Create Card · Retrieve Card                               | 通过 **List Cardholders** 确认 `cardholder_id` 存在于你的账户下且处于生效状态。                                                      |
| `400`  | Cardholder not found or deactivated                                 | List Cards                                                | 确认 `cardholder_id` 过滤条件指向一个在你账户下、处于生效状态的持卡人。                                                                     |
| `400`  | Invalid card type.                                                  | Create Card                                               | 根据卡产品支持的形态，将 `card_type` 设置为 `VIRTUAL` 或 `PHYSICAL`。                                                             |
| `400`  | Card currency is not support                                        | Create Card                                               | 使用所选卡产品允许的 `currency`。可向你的 UQPAY solutions engineer 确认支持的币种。                                                     |
| `400`  | Card limit is illegal                                               | Create Card                                               | 将 `spending_controls.spending_limit` 设置为以最小货币单位表示的正整数，且在产品允许的区间内。                                                |
| `400`  | Update card limit is less than the amount of used card              | Update Card                                               | 新限额必须不低于卡当前已使用的金额。通过 **Retrieve Card** 查看 `available_balance` / `used_amount`，并据此提高限额。                           |
| `400`  | Failed Update. Card Limit should be greater than 0                  | Update Card                                               | 将 `spending_controls.spending_limit` 设置为大于 `0` 的值。                                                               |
| `400`  | Failed Update. Card Limit should be greater than Per transaction    | Update Card                                               | 总的 `spending_limit` 必须大于或等于单笔限额——请提高消费限额或降低单笔上限。                                                                 |
| `400`  | Failed Update. Your transaction limit should be greater than 0      | Update Card                                               | 将单笔限额设置为大于 `0` 的值。                                                                                               |
| `400`  | The single card not support changing card limits                    | Update Card                                               | 一次性卡在创建时已固定限额——创建后不可更改。                                                                                          |
| `400`  | This operation cannot be performed on One-Time Card.                | Update Card · Card Recharge · Card Withdraw               | 一次性卡不支持更新、充值或提现。如需追加资金，请发行一张新卡。                                                                                  |
| `400`  | Card recharge is error                                              | Card Recharge                                             | 用相同的 `Idempotency-Key` 重试。如果持续失败，确认卡的状态、币种以及你的发卡账户余额。                                                            |
| `400`  | Card withdraw not support                                           | Card Withdraw                                             | 该卡产品不支持提现。改用 **Update Card Status** 注销卡片以收回余额。                                                                   |
| `400`  | Card available limit insufficient                                   | Card Withdraw                                             | 提现金额超过卡的可用余额。通过 **Retrieve Card** 查看当前余额，并降低 `amount`。                                                           |
| `400`  | Recharge amount is invalid                                          | Card Recharge                                             | `amount` 必须是以卡币种最小单位（如分）表示的正整数。确认精度与卡币种一致。                                                                       |
| `400`  | Withdraw amount is invalid                                          | Card Withdraw                                             | `amount` 必须是以卡币种最小单位表示的正整数，且不超过当前卡余额。                                                                            |
| `400`  | The card product currently does not support creation                | Create Card                                               | 该卡产品未开放新卡创建。联系你的 UQPAY solutions engineer 启用发卡能力。                                                                |
| `400`  | The card currently does not support withdraw                        | Card Withdraw                                             | 该卡产品禁用了提现。通过 **Update Card Status** 注销卡片以回收余额。                                                                   |
| `400`  | The card currently does not support recharge                        | Card Recharge                                             | 该卡产品禁用了充值（例如一次性卡）。如需追加资金，请发行新卡。                                                                                  |
| `400`  | The card currently does not support cancel                          | Update Card Status                                        | 卡当前状态不能转到已注销（例如已注销或待处理）。请先查询卡查看其状态。                                                                              |
| `400`  | The card has been activated.                                        | Activate Card                                             | 卡已处于激活状态——无需再次激活。用 **Retrieve Card** 确认状态。                                                                       |
| `400`  | Invalid activation code.                                            | Activate Card                                             | 确认 `activation_code` 与实体卡卡封上的激活码一致。激活码每次尝试只能使用一次。                                                                |
| `400`  | Card order is not exists                                            | Retrieve Card Order                                       | 确认 `order_id` 正确，且来自此前某次创建卡的响应。                                                                                  |
| `400`  | Card product is error                                               | Create Card · Activate Card                               | `card_product_id` 配置有误。联系你的 UQPAY solutions engineer 确认该产品已在你的账户上启用。                                             |
| `400`  | Not found card products                                             | Create Card · Update Card · Card Recharge · Card Withdraw | 你的账户下没有匹配的可用卡产品——联系你的 UQPAY solutions engineer 启用该产品。                                                            |
| `400`  | Product not opened                                                  | Card Recharge                                             | 该卡产品未开放充值。联系你的 UQPAY solutions engineer。                                                                         |
| `400`  | Account card quota exceeded.                                        | Create Card · Assign Card                                 | 账户级别的活动卡上限已达到。通过 **Update Card Status** 注销未使用的卡，或向你的 UQPAY solutions engineer 申请提高配额。                            |
| `400`  | Cardholder card quota exceeded.                                     | Create Card · Assign Card                                 | 该持卡人已达到最大活动卡数量。注销其中一张卡，或改用其他持卡人。                                                                                 |
| `400`  | Account balance not exists                                          | Create Card · Card Recharge · Card Withdraw               | 你的账户不持有卡币种对应的余额。请先为发卡账户余额充值——参见 **Fund your issuing balance**。                                                   |
| `400`  | Insufficient balance                                                | Create Card · Card Recharge · Card Withdraw               | 在重试之前，为卡币种对应的发卡账户余额充值。                                                                                           |
| `400`  | Spending controls is error                                          | Update Card                                               | `spending_controls` 载荷校验失败——对照 **Update Card** 的 schema 检查 `spending_limit`、`per_transaction_limit` 以及任何白/黑名单字段。 |
| `400`  | Metadata is invalid                                                 | Update Card                                               | `metadata` 必须是扁平的 `string → string` 映射。移除嵌套对象，并确保键和值在长度限制内。                                                      |
| `400`  | risk control setting is not allowed                                 | Update Card                                               | 该 `risk_controls` 组合在此卡产品下不被允许。支持的配置见 **[卡产品](/zh/card-issuance/v1.6/guide/card-products)** 能力矩阵。                |
| `400`  | Exceed restrict max authorization amount                            | Create Card                                               | 请求的限额超过了产品允许的最大授权金额。降低 `spending_limit`，或请你的 UQPAY solutions engineer 提高产品上限。                                    |
| `400`  | Restrict config error                                               | Update Card                                               | 本次更新违反了卡产品的限制配置——请核对你正在设置的类别、币种或 MCC 白名单。                                                                        |
| `400`  | Not found product restrict                                          | Update Card · Card Recharge · Card Withdraw               | 平台上缺少该卡产品的限制配置。联系你的 UQPAY solutions engineer。                                                                    |
| `400`  | Convert data error                                                  | Create Card · Update Card                                 | 内部数据转换失败——用相同的 `Idempotency-Key` 重试。如果持续失败，请把请求 ID 报给你的 UQPAY solutions engineer。                                |
| `400`  | Content type is not supported, please upload the correct format     | Create Card                                               | 使用 `Content-Type: application/json` 发送请求。                                                                        |
| `400`  | no pin payment amount failed.                                       | Update Card · Activate Card                               | 你提供的 `no_pin_payment_amount` 校验失败。确认取值、精度和币种与卡产品配置一致。                                                            |
| `400`  | Negative no pin payment amount.                                     | Activate Card                                             | `no_pin_payment_amount` 必须是非负整数。                                                                                 |
| `400`  | Invalid no pin payment amount precision.                            | Activate Card                                             | 精度需与卡币种的最小单位一致（例如 USD 为 2 位小数，JPY 为 0 位）。以最小单位的整数发送。                                                             |
| `400`  | invalid no pin payment amount for the current currency.             | Update Card · Activate Card                               | 数值超过了卡币种的允许上限。降低 `no_pin_payment_amount`，或检查产品配置。                                                                |
| `400`  | The no\_pin\_payment\_amount restrict configuration cannot be found | Update Card · Activate Card                               | 该卡产品不支持免密金额上限——请从请求中移除该字段。                                                                                       |
| `429`  | Request is too frequent                                             | Create PAN Token · Retrieve Sensitive Card Details        | 按指数退避重试。这些 endpoint 按卡限流；不要在循环中紧密轮询。                                                                             |

<h3 id="cardholder-errors">持卡人错误</h3>

<Accordion title="相关 endpoint">
  Create Cardholder · List Cardholders · Update Cardholder · Retrieve Cardholder · Create Card（一次性发卡路径）
</Accordion>

*type：`cardholder_error`*

**信封 A**

| `code`                                   | 错误消息                                                                                                       | 典型接口                                                | 处理方式                                                                                     |
| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `cardholder_not_found`                   | cardholder not found or deactivated                                                                        | 任何接收 `{cardholder_id}` 的 endpoint · Create Card     | 通过 **List Cardholders** 确认 `cardholder_id` 存在于你的账户下且处于生效状态。                              |
| `cardholder_already_exists`              | cardholder already exists                                                                                  | Create Card                                         | 系统中已存在具有相同身份信息的持卡人——请复用该持卡人的 `cardholder_id`，不要新建。                                       |
| `email_duplicated`                       | email already used by another cardholder under account                                                     | Create Cardholder · Create Card                     | 更换 `email`，或复用已有的持卡人记录——通过 **List Cardholders** 查询。                                      |
| `phone_number_duplicated`                | phone number used by another cardholder under account                                                      | Create Cardholder · Create Card                     | 更换手机号，或复用已有的持卡人记录——通过 **List Cardholders** 查询。                                           |
| `invalid_phone_number`                   | invalid phone number or country code                                                                       | Create Cardholder · Update Cardholder · Create Card | `phone.country_code` 以纯数字的 ISO 国家电话代码填写，`phone.number` 以 E.164 国内格式的纯数字填写。               |
| `invalid_first_name`                     | invalid first name, only letters and spaces allowed, no leading or trailing spaces                         | Create Cardholder · Create Card                     | `first_name` 仅允许 ASCII 字母和空格。去除首尾空格，并移除标点或数字。                                            |
| `invalid_last_name`                      | invalid last name, only letters and spaces allowed, no leading or trailing spaces                          | Create Cardholder · Create Card                     | `last_name` 仅允许 ASCII 字母和空格。去除首尾空格，并移除标点或数字。                                             |
| `invalid_date_of_birth`                  | cardholder under 18 or invalid date of birth format                                                        | Create Cardholder · Update Cardholder               | 持卡人必须年满 18 岁。`date_of_birth` 以 `YYYY-MM-DD` 格式发送。                                        |
| `missing_date_of_birth`                  | missing legal date of birth for document upload                                                            | Create Cardholder · Update Cardholder · Create Card | 上传身份证件时必须同时提供 `date_of_birth`——证件核验需要该字段。                                                |
| `invalid_delivery_address`               | invalid delivery address                                                                                   | Create Cardholder · Update Cardholder · Create Card | 完整填写寄送地址的所有必填子字段：`country`、`state`、`city`、`postal_code`、`line1`。使用 ISO 国家代码。             |
| `missing_country_code`                   | country\_code is required for SUMSUB\_REDIRECT KYC verification                                            | Create Cardholder · Update Cardholder · Create Card | 当 `kyc_method` 为 `SUMSUB_REDIRECT` 时，需要提供持卡人的居住地 `country_code`（ISO 3166-1 alpha-2）。     |
| `document_duplicated`                    | document already successfully reviewed                                                                     | Update Cardholder                                   | 该身份证件已在持卡人上通过审核——不要重复上传。                                                                 |
| `file_type_not_supported`                | unsupported document file type                                                                             | Create Cardholder · Update Cardholder · Create Card | 以 JPEG、PNG 或 PDF 格式上传证件。                                                                 |
| `invalid_file_content`                   | invalid base64 encoded document content                                                                    | Create Cardholder · Update Cardholder · Create Card | 确认文件字节为标准 Base64 编码（不带 data-URL 前缀、不含换行）后再发送。                                            |
| `document_size_exceeded`                 | document size exceeds 2MB limit                                                                            | Create Cardholder · Update Cardholder · Create Card | 压缩或重新扫描证件，确保解码后文件小于 2 MB。                                                                |
| `document_review_required`               | cardholder's document requires review                                                                      | Create Card                                         | 该持卡人的证件仍在人工审核中。等待 `cardholder.kyc_status` Webhook，或轮询 **Retrieve Cardholder** 直到 KYC 通过。 |
| `identity_file_missing`                  | required identity file is missing                                                                          | Create Cardholder · Update Cardholder · Create Card | 在 `identity_documents` 中上传所需的身份证件（例如身份证的正反两面）。                                           |
| `invalid_identity_type`                  | invalid identity type, must be ID\_CARD or PASSPORT                                                        | Create Cardholder · Update Cardholder · Create Card | 将 `identity_type` 设置为 `ID_CARD` 或 `PASSPORT`。                                            |
| `invalid_kyc_method`                     | invalid KYC verification method, must be THIRD\_PARTY or SUMSUB\_REDIRECT                                  | Create Cardholder · Update Cardholder · Create Card | 将 `kyc_method` 设置为 `THIRD_PARTY` 或 `SUMSUB_REDIRECT`。                                    |
| `kyc_proof_required`                     | kyc\_proof is required when method is THIRD\_PARTY                                                         | Create Cardholder · Update Cardholder · Create Card | 当 `kyc_method` 为 `THIRD_PARTY` 时，提供 `kyc_proof` 载荷以描述你方 KYC 服务商的核验结果。                    |
| `reference_id_duplicated`                | reference\_id already used by another cardholder                                                           | Create Cardholder · Update Cardholder · Create Card | 提供唯一的 `reference_id`——该账户下已有其他持卡人使用了你发送的值。                                               |
| `reference_id_too_short`                 | reference\_id must be at least 10 characters long                                                          | Create Cardholder · Update Cardholder · Create Card | `reference_id` 长度至少为 10 个字符。                                                             |
| `cardholder_kyc_pending`                 | cardholder KYC is under review, cannot proceed                                                             | Create Card                                         | 等待 KYC 完成。轮询 **Retrieve Cardholder** 或监听 `cardholder.kyc_status` Webhook，然后再重试。          |
| `cardholder_kyc_failed`                  | cardholder KYC has been rejected                                                                           | Create Card                                         | 让持卡人重新提交身份证件，或新建一个持卡人记录。如果拒绝原因不明，联系你的 UQPAY solutions engineer。                          |
| `kyc_insufficient`                       | cardholder information does not meet this product's requirements (response includes `missing_fields`)      | Create Card                                         | 通过 **Update Cardholder** 补齐响应中 `missing_fields` 列出的字段，然后重试。                              |
| `supplement_fields_incomplete`           | supplemented cardholder fields are incomplete (response includes `missing_fields`)                         | Create Card                                         | 在重试时，把响应 `missing_fields` 里的每个字段填入 `cardholder_required_fields`。                         |
| `cardholder_cannot_update_during_review` | cannot update KYC fields while review is pending                                                           | Update Cardholder                                   | 等待 KYC 审核结束，再编辑身份或地址字段。非 KYC 字段（如 `metadata`）仍可更新。                                       |
| `bin_required_fields_not_configured`     | required\_fields not configured for this card BIN, cannot proceed with card creation                       | Create Card                                         | 该卡 BIN 的 required\_fields 配置在平台上缺失。联系你的 UQPAY solutions engineer。                        |
| `cardholder_missing_info`                | either cardholder\_id or complete cardholder\_required\_fields must be provided                            | Create Card                                         | 要么提供已存在的 `cardholder_id`，要么在 `cardholder_required_fields` 中提供完整的一次性发卡载荷。                 |
| `cardholder_incomplete_fields`           | cardholder\_required\_fields is incomplete for one-time card issuance (response includes `missing_fields`) | Create Card                                         | 把响应 `missing_fields` 中的每个字段补充到 `cardholder_required_fields`，再重试。                         |

<h3 id="balance-errors">余额错误</h3>

<Accordion title="相关 endpoint">
  Retrieve Issuing Balance · List Issuing Balances · List Issuing Balances Transactions
</Accordion>

*type：`account_error`*

**信封 A**

| `code`                  | 错误消息                                                 | 典型接口                                                                                  | 处理方式                                                                 |
| ----------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| `account_balance_error` | insufficient balance or currency balance unavailable | Retrieve Issuing Balance · List Issuing Balances · List Issuing Balances Transactions | 确认你的账户持有请求 `currency` 对应的余额。调用 **List Issuing Balances** 查看所有可用币种余额。 |

<h3 id="transaction-errors">交易错误</h3>

<Accordion title="相关 endpoint">
  List Cards Transactions · Retrieve Cards Transaction · Claim Unsolicited Refund · Simulate Authorization · Simulate Reversal
</Accordion>

*信封 A 的 type：`invalid_request_error`（交易不存在 / 不属于当前关联账户，或无源退款认领无法处理）。Claim Unsolicited Refund 仅返回信封 A，没有信封 B 错误。*

**信封 A**

| `code`                  | 错误消息                                                                   | 典型接口                       | 处理方式                                                                                        |
| ----------------------- | ---------------------------------------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------- |
| `invalid_request_error` | `transaction[<id>] not found under the connected account`              | Retrieve Cards Transaction | 确认 `transaction_id` 存在于你的账户下。使用 **List Cards Transactions** 查找可用的 ID。                       |
| `invalid_request_error` | original transaction not found or not owned by current account         | Claim Unsolicited Refund   | 确认 `related_transaction_id` 是原授权交易的 `transaction_id`（不是它的 `short_reference_id`），且该交易属于你的账户。 |
| `invalid_request_error` | original transaction is not a valid authorization source transaction   | Claim Unsolicited Refund   | `related_transaction_id` 必须指向一笔成功的授权交易。用 **Retrieve Cards Transaction** 确认源交易的类型与状态。        |
| `invalid_request_error` | no unreferenced refund intercept transaction found to claim            | Claim Unsolicited Refund   | 该原交易下没有等待认领的被拦截无源退款，无可释放。除非你确实预期有退款到账，否则无需处理。                                               |
| `invalid_request_error` | a release request for this original transaction is already in progress | Claim Unsolicited Refund   | 该原交易已有认领申请在处理中。请勿重复提交，等待异步结果。                                                               |
| `invalid_request_error` | unsolicited refund claim only supported on VISA                        | Claim Unsolicited Refund   | 该认领仅支持 Business Visa 卡。原交易的卡不是 Business Visa，无法认领。                                          |

**信封 B**

| `code` | 错误消息                                | 典型接口                                       | 处理方式                                                          |
| ------ | ----------------------------------- | ------------------------------------------ | ------------------------------------------------------------- |
| `400`  | Card authorize transaction is error | Simulate Authorization                     | 重试模拟器调用。如果持续失败，确认目标卡处于激活状态，且金额/币种与该卡匹配。此 endpoint 仅沙盒可用。      |
| `400`  | Card reversal transaction is error  | Simulate Reversal                          | 确认要冲正的 `transaction_id` 存在，且指向此前某次模拟过的授权。此 endpoint 仅沙盒可用。    |
| `400`  | Invalid channel code                | Simulate Authorization · Simulate Reversal | 将 `channel` 设置为支持的沙盒渠道值。可向你的 UQPAY solutions engineer 获取允许列表。 |
| `400`  | MCC is error                        | Simulate Authorization                     | 提供该卡消费限额允许的 4 位数字 `mcc` 代码。                                   |
| `400`  | Account status error                | Simulate Authorization · Simulate Reversal | 账户当前状态无法模拟授权。通过 UQPAY 控制台确认账户处于生效状态。                          |
| `400`  | Restrict config error               | Simulate Authorization · Simulate Reversal | 模拟交易违反了卡的消费限额（MCC、币种、国家或限额）。调整模拟器请求或卡的 `spending_controls`。   |