参考

错误码

开放支付 API 返回的所有 error_code 及处理方式。

错误响应带真实 HTTP 状态码和稳定的 error_code：

json

{ "trace_id": "1a2b3c4d5e6f7a8b", "status_code": 422, "message": "The amount exceeds the app's payment limit.", "error_code": "LIMIT_EXCEEDED" }

请求与签名

`error_code`	HTTP	含义	处理
`INVALID_REQUEST`	400	字段缺失或不合法，`message` 会说明；也包括缺少 / 格式错误的 `Idempotency-Key`、请求体超过 64 KB	修正请求
`SIGNATURE_INVALID`	401	缺少请求头、Key 不存在 / 已吊销 / 已过期、签名错误、时间戳超出 ±5 分钟或 nonce 重复	见常见签名错误
`REPLAY_PROTECTION_UNAVAILABLE`	503	校验 nonce 时出现临时故障	换新 nonce 重试
`IDEMPOTENCY_KEY_REUSED`	409	相同 `Idempotency-Key`，请求体不同	不同操作使用新的 Key
`IDEMPOTENCY_IN_PROGRESS`	409	同一 Key 的首个请求仍在处理	稍后重试
`TOO_MANY_REQUESTS`	429	超过频率限制	等待 `Retry-After` 秒
`INTERNAL_ERROR`	500	服务异常	退避重试；带上 `trace_id` 联系客服

`error_code`	HTTP	含义	处理
`APP_UNAVAILABLE`	403	App 被停用 / 下线、开发者被停用，或未发布 App 发起生产订单	在控制台查看 App 状态
`PAYMENT_NOT_ENABLED`	403	支付未开通或已被停用	在控制台申请 / 联系客服
`PAYOUT_NOT_ALLOWED`	403	条款中不包含付款功能	重新申请并勾选付款
`DEVELOPER_WALLET_UNAVAILABLE`	403	你的钱包被冻结或不存在	联系客服
`SANDBOX_USER_ONLY`	403	沙箱订单的对象不是测试用户	添加为测试用户，或使用生产环境

`error_code`	HTTP	含义	处理
`INVALID_AMOUNT`	422	非正数、超过 2 位小数，或不大于手续费	修正金额
`CURRENCY_NOT_SUPPORTED`	422	币种不是 `USDT`	传 `USDT`
`LIMIT_EXCEEDED`	422	超过单笔、日或月限额	降低金额、次日再试或申请提高限额
`ORDER_ALREADY_EXISTS`	409	`out_order_no` / `out_refund_no` 在本环境已使用	查询该订单，而不是重新创建
`ORDER_NOT_FOUND`	404	本 App 在本环境下没有该订单	检查 ID 以及使用的 Key
`INVALID_STATE`	409	如关闭已支付的收款单	改为退款
`USER_NOT_AUTHORIZED`	422	该 `sub` 从未登录你的 App、已取消授权或账号不可用	请用户重新用 HTP 登录
`SELF_PAYMENT_FORBIDDEN`	422	向你自己的开发者账号收款或付款	使用其他账号 / 测试用户
`REFUND_NOT_ALLOWED`	409	收款单不是 `PAID`	只能对已支付订单退款
`REFUND_AMOUNT_EXCEEDED`	422	超过 `amount − refunded_amount`	降低退款金额
`INSUFFICIENT_BALANCE`	422	你的钱包余额不足以退款或付款	为钱包充值

你不会收到这些错误，但用户可能会向你反馈：

错误码	对用户的含义
`CHECKOUT_EXPIRED`	订单已过期或已被关闭 —— 请重新下单
`CHECKOUT_ALREADY_PAID`	已支付 —— 请检查回调 / 订单状态
`CHECKOUT_PAYER_MISMATCH`	该订单指定了其他付款人（`payer_sub`）
`INSUFFICIENT_WALLET_BALANCE`	用户余额不足，需要充值
`WALLET_UNAVAILABLE`	用户钱包被冻结
`LIMIT_EXCEEDED`	创建到确认期间达到了你的限额
`INCORRECT_PIN` / `TOO_MANY_PIN_ATTEMPTS`	PIN 错误；错 4 次锁定 1 分钟