错误码

当 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（旧版幂等处理中）

资源错误

支付错误

退款错误

客户错误

出款错误

​错误响应格式

​错误类型

​通用错误

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

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

​资源错误

​支付错误

​退款错误

​客户错误

​出款错误

错误响应格式

错误类型

通用错误

信封 A（带类型的错误）

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

资源错误

支付错误

退款错误

客户错误

出款错误