文档 / 参考

错误码

错误响应体的结构始终相同。请以 code 为准，而不是文本：文本是写给人看的，可能会变化。

JSON

{ "error": { "code": "duplicate_order", "message": "该 order_id 的账单已创建" } }

何时可以安全重试遇到 429、500、503、idempotency_in_progress 以及网络错误时，使用相同的 Idempotency-Key 重试：不会产生重复。

请求与访问

HTTP	code	原因及处理方法
400	`bad_json`、`bad_body`	请求体不是 JSON、包含多余字段，或金额用了数字而非字符串：请修正请求
400	`bad_idempotency_key`	缺少幂等键或格式错误：需为 8–128 个可打印 ASCII 字符，且不能以 `d:` 开头
400	`bad_query`	列表参数无效
401	`unauthorized`	签名、时间、nonce 或密钥有误：参见 CP-HMAC
403	`merchant_suspended`	商户已被暂停：请联系客服
403	`merchant_not_approved`	接入尚未完成或申请正在审核中：请在后台完成接入向导
403	`billing_suspended`	平台手续费账单未支付：请在后台「计费」中支付，暂停将立即解除
404	`not_found`	账单不存在或不属于您
413	`body_too_large`	请求体超出限制：请精简 `metadata`
429	`rate_limited`	请求过多：请以指数退避方式重试
500	`internal`	内部错误：请使用相同的 `Idempotency-Key` 重试

HTTP	code	原因及处理方法
409	`duplicate_order`	`order_id` 已被使用：请换一个新的，例如 `ORDER-1001-2`
409	`idempotency_conflict`	相同的幂等键搭配了不同的请求体
409	`idempotency_in_progress`	首次请求仍在处理中：1–2 秒后重试
409	`invoice_not_payable`	账单已过期或已关闭：请创建新账单
422	`invalid_order_id`、`invalid_price_amount`、`invalid_price_currency`、`invalid_return_url`、`invalid_expires_in_seconds`、`invalid_metadata`	字段未通过校验：错误文本会提示具体规则
422	`invalid_allowed_assets`	列表中没有任何可用资产：错误文本会逐一说明原因
422	`no_assets`	没有任何可用资产：请在后台检查钱包和资产设置
422	`amount_too_small`	金额低于所有可用资产的最低金额

这些错误由支付页面处理：只有当您自己调用 select 时，您的服务器才会遇到它们。

HTTP	code	原因
409	`asset_locked`	付款后尝试更换币种
409	`wallet_not_configured`	该网络没有有效的收款钱包
409	`wallet_changed`、`address_conflict`	请重新选择
422	`asset_not_allowed`	该资产不在账单中，或已不再允许
503	`rate_unavailable`	暂无经确认的汇率：请建议顾客使用稳定币
503	`network_unavailable`	该网络暂时无法收款：请选择其他网络

HTTP	code	原因
403	`merchant_inactive`	商店已被暂停或密钥已被吊销
409	`invoice_not_paid`	账单未选择资产：没有可退的款项
409	`nothing_to_refund`	款项已全部退还或已申请退款
409	`too_many_refunds`	该账单已有 20 个未完成的退款申请
409	`refund_executor`	该退款由平台执行，而不是由您执行
409	`invoice_status_changed`	提交申请后账单状态发生了变化：请带上 `"ack_status_change": true` 重试
422	`amount_exceeds_refundable`	金额超出可退金额：请减少金额或使用 `"full"`
422	`invalid_amount`、`invalid_address`、`invalid_tx_hash`	字段未通过校验