错误码与排查
平台的错误信息都是给人看的句子，不是一串数字。这一页按"现象 → 原因 → 怎么办"整理， 用可读的类别名而不是编号，便于你直接照着排查。
HTTP 状态与类别
开放接口的调用方是程序，所以它会用真实的 HTTP 状态码，让你在不解包正文的情况下也能分流：
| 类别 | 典型状态码 | 现象 | 怎么办 |
|---|---|---|---|
| API KEY 无效 | 401 | 返回"API KEY 无效或已失效，请核对请求头 X-Pay-Api-Key" | 检查头名是否拼对、KEY 有没有多余空格、是否已轮换。平台不区分失败原因，就是为了不泄漏"这个 KEY 存在" |
| 商户状态不允许 | 403 | 返回具体原因（如未开通线上收款、商户已停用） | 这是给你看得懂的理由，不是 KEY 的问题。按提示去申请开通或联系平台 |
| 平台暂时不可用 | 503 | 服务端内部错误 | 不是你的问题，按你的重试策略稍后重试；503 不该触发你"去轮换 KEY" |
| 触发限流 | 429 | 提示请求过于频繁 | 降低频率或加退避重试。下单按商户限流、查询额度更宽；限流计数器按来源 IP 与商户号分别统计 |
| 参数不合法 | 业务错误码 + 可读 msg | 如"缺少商家订单号（merchantOrderNo）" | 按 msg 修正请求体 |
| 下单被拒 | 业务错误码 + 可读 msg | 如"金额低于最小限额" | 被拒原因原样转达，修正后重试；这类不消耗幂等额度 |
粗看状态码，细看 msg
状态码用来分流（该改配置、该等一会儿、还是该改参数），msg 用来看具体原因。 两者都给你，是因为程序和人需要的粒度不一样。
常见问题
| 现象 | 可能原因 | 排查顺序 |
|---|---|---|
| API KEY 无效 | 头名写错（不是 Authorization，是 X-Pay-Api-Key）；KEY 前后带空格/换行（从环境变量读时常见）；KEY 已轮换且过了过渡期 | ① 打日志确认头名与 KEY 末 4 位 ② 环境变量是否带了引号或换行 ③ 是否刚轮换过 KEY |
| 金额低于最小限额 | 下单金额小于该代币配置的最小值 | ① 从链与代币清单读 minAmount ② 确认 amount 是代币单位小数字符串（开放接口），不是最小单位整数串 |
| 金额形态传错 | 开放接口要 "100.5"，收银页要 "100500000"，两者相反 | ① 确认调的是哪个接口 ② 用 decimals 换算核对数量级，差 10 的幂通常就是这里 |
| 幂等重放 | 同一 merchantOrderNo 重复调用，返回已有订单，idempotentReplay=true | 这是正常行为，不是错误。想确实再开一单，就换一个新的 merchantOrderNo |
| 限流 | 短时间请求过多 | ① 确认不是重试风暴（幂等重试本身也会计数） ② 加指数退避 ③ 若为常态超限，联系平台调整档位 |
| 回调地址不可达 | 换了域名、发版期间不可达、防火墙改规则、地址是内网地址 | ① 从公网能否访问该 URL ② 是否只放行 POST ③ 是否 http(s) ④ 回复是否在超时内（约 10 秒） |
| 回调验签不通过 | 用了解析后重编码的正文；时间戳拼接方式不对；密钥不是 API KEY；轮换后没更新 | ① 用原始报文字节算签名 ② timestamp + body 字符串拼接 ③ 密钥确认是当前 KEY |
| 订单一直"待支付" | 买家还没转，或转到了别的地址，或金额与识别信息没带对 | ① 用查询接口看 receivedAmountMinimal ② 确认买家按 payAddress + payAmountMinimal + identify 转 ③ 链上拥堵时确认会慢 |
| 订单"已提交"很久不动 | 确认数还没攒够 | 看查询结果里的 confirmations / requiredConfirmations。已提交 不等于已付款，别在这个状态下发货 |
| 订单"待人工认领" | 链上有一笔钱分不清属于哪张单（如同地址两笔同额） | 系统刻意不猜，猜错等于把 A 单标成已付而 B 单永远收不到钱。主动联系平台做人工认领 |
| 金额对不上（差一点） | 把最小单位当成了代币单位，或反过来；或用了浮点换算 | 统一用最小单位整数字符串比对，别用浮点 |
排查时先确认这几件事
- 你调的是哪一组接口。 开放接口要 API KEY，商户侧接口要 JWT，收银页公开接口无需登录 —— 走错组就是
401。 - 金额的形态。 开放接口小数字符串，收银页最小单位整数串。数量级不对先怀疑这里。
- 订单状态用名字判断，不要用数值大小。 状态数值不是按付款程度排序的。
- 回调不等于钱到没到。 关键动作前用查询订单核对。
需要人工协助
尚未开放
匿名在线客服尚未上线。 遇到上面表格里没有的情况，请通过官网注册入口或邮箱联系我们， 并附上你的 merchantNo 与相关 orderNo，便于快速定位。