> ## 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.
# 错误码
> 查阅 Global Acquiring API 返回的错误码、出现位置，以及遇到时如何处理。
当 Global Acquiring API 调用失败时，网关会返回非 2xx 的 HTTP 状态码，并附带 JSON 错误体。请使用本页识别出错原因以及如何恢复。
Global Acquiring API 使用**两种响应信封**，具体返回哪一种取决于处理该请求的 handler。
Global Acquiring API 返回的几乎所有错误都使用此信封。`type` 字段决定了 HTTP 状态码（参见[错误类型](#error-types)）。
```json theme={null}
{
"type": "payment_error",
"code": "retrieve_payment_intent_failed",
"message": "Retrieve payment intent failed"
}
```
| 字段 | 含义 |
| --------- | ------------------------------------------ |
| `type` | 高层分类。映射到 HTTP 状态码（参见[错误类型](#error-types)）。 |
| `code` | 机器可读的字符串标识，用于程序化处理。 |
| `message` | 人类可读的描述。可安全写入日志，但不适合直接原样展示给终端用户。 |
当请求复用了仍在处理中的 `Idempotency-Key` 时，幂等中间件会返回一个扁平结构，其中 `code` 为数字字面量，HTTP 状态码为 400，并且没有 `type` 字段。
```json theme={null}
{
"code": 200,
"message": "Request is processing, please try again later."
}
```
| 字段 | 含义 |
| --------- | ----------------------------- |
| `code` | 数字字面量。仅当原始请求仍在处理中时才会返回 `200`。 |
| `message` | 人类可读的描述。 |
处理响应时，请根据是否存在 `type` 字段来选择对应的信封格式。信封 B 永远不会携带 `type`。
错误类型
信封 A 将错误码按 `type` 分组，每种 `type` 映射到固定的 HTTP 状态码。
| `type` | HTTP | 出现场景 |
| ----------------------- | --------------- | ------------------------------------------------------------------------------------- |
| `invalid_request_error` | 400 | 请求未通过校验。 |
| `idempotency_error` | 400 | 幂等键格式无效或不匹配。 |
| `account_error` | 400 | Account 或 bank-account 资源规则被违反。 |
| `customer_error` | 400 | Customer 资源规则被违反。 |
| `payment_error` | 400 | PaymentIntent、PaymentAttempt 或 payment link 资源规则被违反。 |
| `refund_error` | 400 | Refund 资源规则被违反。 |
| `payout_error` | 400 | Payout 资源规则被违反。 |
| `product_error` | 400 | 商户的产品配置不允许执行此操作。 |
| `not_found` | 400 | 在关联账户下未找到指定的资源 id。 |
| `unauthorized_error` | 401 | API key 或 client secret 缺失、格式错误或已过期。 |
| `api_error` | 400 / 429 / 500 | 网关内部错误或风控错误的兜底分类；`code` 为 `api_error` 时返回 HTTP 500，`velocity_limit_exceeded` 时返回 429。 |
信封 B 不携带 `type` 字段；请根据 `code` 是数字（信封 B）还是字符串（信封 A）来区分两种格式。
通用错误
以下错误可能出现在任意已认证的接口上。
信封 A（带类型的错误）
| `code` | `type` | Message | 处理建议 |
| -------------------------------- | ----------------------- | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `invalid_parameter` | `invalid_request_error` | *（取决于场景 —— JSON/query 绑定失败时为 `parameter is invalid`，校验器失败时为 `Invalid request parameters: `）* | 对照该接口的 API reference 检查请求体 —— 有一个或多个字段未通过 JSON 绑定或 schema 校验。当 message 指出具体字段时，修正该字段后重试。 |
| `missing_parameter` | `invalid_request_error` | Mandatory parameter is missing | 补全 message 中指出的必填 path 参数或 body 字段。最常见的情况是缺少 `{id}` 段，或请求体中某个必填字段为空。 |
| `unauthorized_error` | `unauthorized_error` | *（取决于场景 —— 例如 `auth token is not empty`、`invalid auth token format`、`auth token is expired`）* | 通过 **Request an access token** 获取新的 token，并放入 `x-auth-token` 请求头。Token 会过期 —— 重试前请先刷新。 |
| `account_not_found` | `account_error` | Account not found or deactivated | 确认 access token 解析出的商户账户处于有效状态。如果账户是刚刚创建或被暂停，请先联系 UQPAY 支持再重试。 |
| `invalid idempotency key format` | `idempotency_error` | Idempotency key is invalid | 发送一个非空的 `Idempotency-Key` 请求头，且格式需符合该接口文档的要求（通常为 UUID）。重新生成 key 后重试。 |
| `api_error` | `api_error` | An internal error occurred, please try again. | 短暂退避后，使用相同的 `Idempotency-Key` 重试请求。如果错误持续出现，请联系 UQPAY 支持，并提供响应头中的 `request_id`。 |
信封 B（旧版幂等处理中）
| `code` | Message | 处理建议 |
| ------ | ---------------------------------------------- | --------------------------------------------------------- |
| `200` | Request is processing, please try again later. | 短暂后使用相同的 `Idempotency-Key` 重试 —— 原始请求仍在处理中，一旦完成，最终响应会被返回。 |
资源错误
支付错误
Create a PaymentIntent · Retrieve a PaymentIntent · Update a PaymentIntent · Confirm a PaymentIntent · Capture a PaymentIntent · Cancel a PaymentIntent · List all PaymentIntents · Retrieve a PaymentAttempt · List all PaymentAttempts
*信封 A 涉及的 type：`payment_error`、`invalid_request_error`、`product_error`、`not_found`。*
**信封 A**
| `code` | Message | 典型 endpoint | 处理建议 |
| --------------------------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `create_payment_intent_failed` | Create payment intent failed | Create a PaymentIntent | 网关在持久化 PaymentIntent 时发生内部故障。使用相同的 `Idempotency-Key` 重试；如果持续失败，请联系 UQPAY 支持并附上 `request_id`。 |
| `create_payment_attempt_failed` | Create payment attempt failed | Create a PaymentIntent · Confirm a PaymentIntent | 网关在创建 attempt 记录时发生内部故障。使用相同的 `Idempotency-Key` 重试；如错误反复出现，请联系支持。 |
| `confirm_payment_intent_failed` | Confirm payment intent failed | Create a PaymentIntent · Confirm a PaymentIntent | 向渠道确认支付失败。重试前请通过 **Retrieve a PaymentIntent** 查看当前 `status` —— 该 attempt 可能已在处理中。 |
| `retrieve_payment_intent_failed` | Retrieve payment intent failed | Retrieve a PaymentIntent · Update a PaymentIntent · Confirm a PaymentIntent · Capture a PaymentIntent · Cancel a PaymentIntent · Create a refund | 检查 URL 中的 PaymentIntent `id` 是否存在且归属于当前认证账户。不要去掉 `pi_` 前缀。 |
| `retrieve_payment_attempt_failed` | Retrieve payment attempt failed | Retrieve a PaymentAttempt · Capture a PaymentIntent · Cancel a PaymentIntent · Create a refund | 确认该 `payment_attempt` id 确实存在于对应的 PaymentIntent 下。可使用 **Retrieve a PaymentIntent** 列出有效的 attempt id。 |
| `update_payment_intent_failed` | Update payment intent failed | Update a PaymentIntent | 通过 **Retrieve a PaymentIntent** 检查 PaymentIntent 的 `status` —— 只有处于 `requires_payment_method` 或 `requires_confirmation` 状态的 intent 才允许更新。 |
| `capture_payment_intent_failed` | Capture payment intent failed | Capture a PaymentIntent | 网关在把请款请求转发到渠道时发生内部故障。重试前请通过 **Retrieve a PaymentIntent** 确认请款是否已经成功。 |
| `capture_amount_invalid` | Amount requested is inconsistent with order amount, Please enter the correct amount. | Capture a PaymentIntent | 把 `amount_to_capture` 设为大于零且不超过 PaymentIntent 已授权金额的值。若需全额请款，直接省略该字段。 |
| `cancel_payment_intent_failed` | Cancel payment intent failed | Cancel a PaymentIntent | 通过 **Retrieve a PaymentIntent** 确认该 PaymentIntent 仍可取消（状态为 `requires_capture` 或更早）。已完成或已取消的 intent 无法再次取消。 |
| `invalid_order_status` | Invalid order status | Update a PaymentIntent · Capture a PaymentIntent · Cancel a PaymentIntent · Create a refund | PaymentIntent 的当前 `status` 不允许执行该操作。请使用 **Retrieve a PaymentIntent** 查询状态，然后调用适合当前状态的接口。 |
| `expired_order` | Expired payment intent | Update a PaymentIntent | PaymentIntent 已超过过期时间。请创建一个新的 PaymentIntent，而不是继续更新这个。 |
| `order_cancelled` | Order cancelled | Cancel a PaymentIntent | 该 PaymentIntent 已处于 `canceled` 状态。无需再执行任何操作。 |
| `operation_pending` | Operation pending! Do not repeat submissions! | Cancel a PaymentIntent | 之前的取消请求仍在处理中。请稍等片刻，并调用 **Retrieve a PaymentIntent** 确认最终状态后再重试。 |
| `repeat_payment_request` | Operation failed. Payment request has been completed for the order. No need to repeat operation. | Capture a PaymentIntent | 该 PaymentIntent 已经完成请款。调用 **Retrieve a PaymentIntent** 读取结果状态即可 —— 无需重试。 |
| `invalid_payment_method` | invalid pay method | Create a PaymentIntent · Confirm a PaymentIntent | 使用账户下已启用，且对该订单币种和客户所在国家支持的 `payment_method` 值。请在商户后台查看已启用的支付方式。 |
| `invalid_return_url` | Invalid return url | Create a PaymentIntent | `return_url` 必须为绝对路径的 HTTPS URL，且需可访问，不得包含未编码的空格或会破坏 URL 解析的 fragment。 |
| `invalid_description` | Invalid description | Create a PaymentIntent | 将 `description` 截短到文档规定的长度（256 个字符）以内，并去除不允许的字符。 |
| `invalid_order_amount` | Invalid order amount | Create a PaymentIntent | `amount` 应为正整数，单位为币种的最小单位（例如 USD 的分）。请检查所选 `payment_method` 的最小和最大额度限制。 |
| `invalid_order_currency` | Invalid order currency | Create a PaymentIntent · Confirm a PaymentIntent | 使用账户对所选 `payment_method` 支持的 ISO 4217 币种代码。部分支付方式（例如 PayNow）仅支持特定币种。 |
| `invalid_payment_orders` | Invalid payment orders | Create a PaymentIntent | `payment_orders` 中各子订单金额之和与顶层 `amount` 不一致，或包含无效条目。请核对每个子订单的金额和币种。 |
| `not_found_id` | Not Found ID | Retrieve a PaymentIntent | 当前账户下不存在该 PaymentIntent `id`。请确认 id 值，并确保使用了正确的 API key 调用。 |
| `product_not_found` | Product not found or inactive | Create a PaymentIntent · Confirm a PaymentIntent · Cancel a PaymentIntent | 该账户对此 `payment_method` 的产品配置缺失或未激活。请联系 UQPAY 支持开通产品。 |
| `3ds_required` | 3DS Required | Create a PaymentIntent · Confirm a PaymentIntent | 发卡行要求对本次交易执行 3DS 验证。请在请求中设置 `3ds.required = true`，并在持卡人浏览器中处理返回的挑战 URL。 |
| `require_payment_pii` | *（取决于场景 —— `invalid payment method body`、`invalid payer info`、`invalid payer identifier` 等）* | Create a PaymentIntent · Confirm a PaymentIntent | 所选 `payment_method` 需要补充付款人资料（姓名、邮箱、证件号或账单地址）。请根据 message 提示填充对应支付方式所需的 PII 字段。 |
| `retrieve_refund_failed` | Retrieve refund failed | Cancel a PaymentIntent · Create a refund · Retrieve a refund | 确认退款 `id` 归属于当前账户。在 cancel/refund 流程中，若先前发起的退款无法再次读取，短暂等待后重试。 |
| `payment_link_not_found` | Payment link not found | Create a PaymentIntent | 请求中引用的 `payment_link` id 不存在。请确认该支付链接在当前账户下存在且未被删除。 |
| `payment_link_expired` | This link can no longer accept payments. Contact the seller for more information. | Create a PaymentIntent | 支付链接已超过其 `expires_at` 时间。请让商户重新生成一个支付链接。 |
| `payment_link_inactive` | This link can no longer accept payments. Contact the seller for more information. | Create a PaymentIntent | 支付链接已被停用。请让商户重新启用，或重新生成一个支付链接。 |
| `payment_link_access_number_not_enough` | This link can no longer accept payments. Contact the seller for more information. | Create a PaymentIntent | 支付链接已达到配置的使用次数上限。请让商户调高访问次数，或重新生成一个支付链接。 |
| `payment_link_parameters_error` | Payment link parameters error | Create a PaymentIntent | 请求参数（金额、币种或客户信息）与支付链接允许的配置不一致。请将请求与链接配置对齐。 |
退款错误
Create a refund · Retrieve a refund · List all refunds
*信封 A 涉及的 type：`refund_error`、`payment_error`、`invalid_request_error`、`api_error`。*
**信封 A**
| `code` | Message | 典型 endpoint | 处理建议 |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------------- |
| `create_refund_failed` | Create refund failed | Create a refund | 网关在创建退款时发生内部故障。使用相同的 `Idempotency-Key` 重试；如错误反复出现，请联系 UQPAY 支持并附上 `request_id`。 |
| `refund_processing` | Refund is processing, please try again after | Create a refund | 该 PaymentIntent 上已有一笔退款正在处理。请通过 **Retrieve a refund** 或退款 webhook 等待其结果，再发起下一笔退款。 |
| `refund_stat_failed` | Find refund order failed | Create a refund | 确认退款引用的 `payment_intent` 存在，且处于可退款状态。 |
| `refund_amount_exceeded` | Refund amount exceeded original transaction amount | Create a refund | 调低 `amount`，使该 PaymentIntent 下所有退款的累计金额不超过已请款金额。 |
| `refund_amount_invalid` | Refund amount invalid | Create a refund | `amount` 应为正整数，单位为币种的最小单位。必须大于零且不超过剩余可退金额。 |
| `retrieve_refund_failed` | Retrieve refund failed | Retrieve a refund · Create a refund · Cancel a PaymentIntent | 确认退款 `id` 归属于当前账户。若退款刚刚创建可能尚未可见，请短暂等待后重试。 |
| `api_error` | Please use the payment cancel endpoint | Create a refund | PaymentIntent 仍处于不适合退款的状态 —— 请改为调用 **Cancel a PaymentIntent**。 |
| `invalid_parameter` | *（取决于场景 —— `invalid start_time`、`invalid end_time`、`the end_time cannot be earlier than the start_time`、`the start_time and end_time cannot differ by more than 90 days`）* | List all refunds | `start_time` 与 `end_time` 使用 RFC 3339 时间戳，确保 `end_time` 晚于 `start_time`，且时间窗口不超过 90 天。 |
客户错误
Create a customer · Get a customer · Update a customer · List customers
*type：`customer_error`*
**信封 A**
| `code` | Message | 典型 endpoint | 处理建议 |
| -------------------------- | ------------------------ | ----------------- | --------------------------------------------------------------------------------------- |
| `create_customer_failed` | Create customer failed | Create a customer | 网关在持久化 customer 时发生内部故障。使用相同的 `Idempotency-Key` 重试；如果持续失败，请联系 UQPAY 支持并附上 `request_id`。 |
| `update_customer_failed` | Update customer failed | Update a customer | 确认 customer `id` 存在于当前账户下，且更新的字段通过了 schema 校验。使用相同的 `Idempotency-Key` 重试。 |
| `retrieve_customer_failed` | Retrieve customer failed | Get a customer | 确认 customer `id` 存在且归属于当前认证账户。 |
出款错误
Create Payout · Retrieve Payout · List all Payouts · Retrieve Balance · List Balances · Create Bank Account · Retrieve Bank Account · Update Bank Account · List all Bank Accounts
*信封 A 涉及的 type：`payout_error`、`account_error`、`product_error`、`api_error`。*
**信封 A**
| `code` | Message | 典型 endpoint | 处理建议 |
| ------------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------- |
| `create_payout_failed` | Create payout failed | Create Payout | 网关在创建出款时发生内部故障。使用相同的 `Idempotency-Key` 重试；如错误反复出现，请联系 UQPAY 支持并附上 `request_id`。 |
| `payout_not_found` | payout not found | Retrieve Payout | 确认出款 `id` 存在且归属于当前认证账户。 |
| `payout_settlement_account_not_found` | No account settlement for this currency | Create Payout | 你的账户尚未为该币种配置结算账户。请联系 UQPAY 支持开通该币种的出款能力。 |
| `invalid_currency` | Invalid currency | Retrieve Balance · Create Bank Account · Create Payout | 使用与账户已启用币种匹配的 ISO 4217 币种代码。请在商户后台查看支持的币种列表。 |
| `insufficient_balance` | Merchant's available balance is insufficient | Create Payout | 调低出款 `amount`，或在重试前先充值。可通过 **List Balances** 读取指定币种当前的可用余额。 |
| `merchant_account_invalid` | Merchant Account Invalid | Create Payout | 商户账户未配置出款能力。请联系 UQPAY 支持开通出款产品。 |
| `disabled_transfer_type` | This type of payout is disabled by the merchant (e.g., auto-withdrawal turned off) | Create Payout | 账户已停用该 `transfer_type`（例如自动出款）。请在商户后台开启该设置，或选择其他 `transfer_type`。 |
| `velocity_limit_exceeded` | Transaction frequency/amount exceeds risk control thresholds (HTTP 429) | Create Payout | 放慢出款创建速度，在限流窗口过后再重试。如果频繁触发限制，请联系 UQPAY 讨论提高额度。 |
| `product_not_found` | Product not found or inactive | Create Payout | 出款产品未在你的账户下激活。请联系 UQPAY 支持开通。 |
| `bank_account_not_found` | Bank account not found | Retrieve Bank Account · Update Bank Account | 确认 bank account `id` 存在且归属于当前认证账户。 |
| `bank_account_already_exists` | Bank account already exists for this currency | Create Bank Account | 通过 **Update Bank Account** 更新该币种已有的 bank account，而不是再创建一个新的。每个币种只允许存在一个 bank account。 |
| `create_bank_account_failed` | Create bank account failed | Create Bank Account | 网关在持久化 bank account 时发生内部故障。使用相同的 `Idempotency-Key` 重试；如错误反复出现，请联系支持。 |
| `update_bank_account_failed` | Update bank account failed | Update Bank Account | 确认 bank account `id` 以及更新的字段通过了 schema 校验。使用相同的 `Idempotency-Key` 重试。 |
| `internal_error` | Internal Error: Please contact support for assistance | Retrieve Payout · List Balances · Create Bank Account · List all Bank Accounts | 短暂退避后，使用相同的 `Idempotency-Key` 重试。如果错误持续出现，请联系 UQPAY 支持，并提供响应头中的 `request_id`。 |
| `invalid_parameter` | Invalid request parameters: `` | Retrieve Payout · Update Bank Account · Create Payout | 修正 message 中指出的字段后重试。校验器会明确指出未通过 schema 校验的具体字段。 |