错误码

当 Global Acquiring API 调用失败时，网关会返回非 2xx 的 HTTP 状态码，并附带 JSON 错误体。请使用本页识别出错原因以及如何恢复。

错误响应格式

Global Acquiring API 使用两种响应信封，具体返回哪一种取决于处理该请求的 handler。

信封 A —— 带类型的错误
信封 B —— 旧版幂等处理中

Global Acquiring API 返回的几乎所有错误都使用此信封。type 字段决定了 HTTP 状态码（参见错误类型）。

{
  "type": "payment_error",
  "code": "retrieve_payment_intent_failed",
  "message": "Retrieve payment intent failed"
}

字段	含义
`type`	高层分类。映射到 HTTP 状态码（参见错误类型）。
`code`	机器可读的字符串标识，用于程序化处理。
`message`	人类可读的描述。可安全写入日志，但不适合直接原样展示给终端用户。

当请求复用了仍在处理中的 Idempotency-Key 时，幂等中间件会返回一个扁平结构，其中 code 为数字字面量，HTTP 状态码为 400，并且没有 type 字段。

{
  "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: <field>`）	对照该接口的 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` 重试 —— 原始请求仍在处理中，一旦完成，最终响应会被返回。

资源错误

支付错误

相关 endpoint

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	请求参数（金额、币种或客户信息）与支付链接允许的配置不一致。请将请求与链接配置对齐。

退款错误

相关 endpoint

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 天。

客户错误

相关 endpoint

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` 存在且归属于当前认证账户。

出款错误

相关 endpoint

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: `<field>`	Retrieve Payout · Update Bank Account · Create Payout	修正 message 中指出的字段后重试。校验器会明确指出未通过 schema 校验的具体字段。

入门

收款集成

支付管理

测试

参考

错误响应格式

错误类型

通用错误

信封 A（带类型的错误）

信封 B（旧版幂等处理中）

资源错误

支付错误

退款错误

客户错误

出款错误

入门

收款集成

支付管理

测试

参考

Documentation Index

​错误响应格式

​错误类型

​通用错误

​信封 A（带类型的错误）

​信封 B（旧版幂等处理中）

​资源错误

​支付错误

​退款错误

​客户错误

​出款错误

错误响应格式

错误类型

通用错误

信封 A（带类型的错误）

信封 B（旧版幂等处理中）

资源错误

支付错误

退款错误

客户错误

出款错误