开发指南
错误码
先看 HTTP 状态，再按接口决定下一步。除历史特殊通道原单已保存的完整永久拒绝和取消冲突外，业务接口的拒绝正文为 {"error":"rejected"}，不包含可用于区分原因的业务错误码。取消未广播提现返回 409 时，正文固定为 {"error":"conflict"}。网关错误可能使用其他正文。
| 结果 | 含义 | 下一步 |
|---|---|---|
200 | 请求成功 | 按该接口的返回字段处理；不等于充值或提现已完成 |
401 | 身份验证未通过。取址和充值接口在正文读取失败或超过 1 MiB 时也返回 401 | 检查环境凭据、Unix 秒、签名原文。提现提交、取消、玩家提现列表和通知配置的超限正文是 422，不是 401 |
取址 422 | 参数不合要求，或当前无法提供地址 | 先查 playerId、chainId 和多余字段；参数正确时，请平台核对地址服务及工厂配置 |
充值查询 422 | 路径、query 或 body 不合要求 | 按接口删除多余参数；GET 不发送 body |
充值查询 404 | 当前未查到该 txRef | 继续核实玩家、链与同步情况；不能按链上失败或失效处理 |
提现提交 422 | 当前普通通道返回通用错误，包括每日上限拒绝；历史特殊通道原单可能返回完整拒绝 | 通用错误保留预扣并核实请求；参数或链等预校验失败不会生成通知，不能只等通知或仅凭 422 释放 |
提现查询 422 | 订单号格式错误、多余 query 或非空 body | 核对原订单号并修正查询请求后再查；不能当作提交被拒绝 |
提现查询 404 | 查询时没有该订单的接入记录 | 在途提交仍可能随后成功；结果未知时保持预扣并继续核实 |
提现查询 503 | 受理结果或查询记录暂不可用 | 保持原订单号查询；此响应无法区分处理中、已拒绝或记录尚未齐备 |
取消提现 409 | 订单已进入处理、已有交易行、凭证已接管，或公开状态已经是其他终态 | 正文为 {"error":"conflict"}。尚未终态时保持预扣和原状态；已经是 failed 或 succeeded 时保持该终态，不新增通知 |
取消提现 422 | 订单号、query 或 body 不合要求 | 与提现查询一样，不带 query 和 body；不能当作已取消 |
取消提现 404 | 没有该订单的接入记录 | 与提现查询 404 相同，不能据此释放预扣 |
取消提现 503 | 钱包或本地终态暂时写不下去 | 保持预扣，用原订单重试；不要换成新订单号 |
玩家提现列表 422 | 玩家路径、链或分页参数不合法，或携带多余参数/body | 核对 chainId/page/pageSize、页码及 offset 边界，不改原订单 |
玩家提现列表 503 | 列表依赖不可用或原单事实损坏 | 保留 OG 本地记录和预扣，重试查询；持续失败请平台检查原单和依赖 |
通知配置 503 | 当前读不到通知配置 | 检查平台配置与服务日志。不能回退旧地址，也不影响原账本查询 |
超时、断线、500/502/503/504 等 | 本次调用结果不确定 | 读取接口可用相同参数重试；提现用原订单号、原内容重试或查询，不释放预扣、不换单号 |
提现异常的原则：结果不确定，保留原订单和预扣。 泛化 422 后再查到一次 404 也不能证明旧请求永远不会被受理。只有查清原请求未受理、没有在途或结果未知的提交后，才能按业务流程修正请求或解除预扣；不能只凭公共错误正文自动判断。
充值列表的 200 + items:[] 表示当前没有匹配记录。取址或充值查询返回 200，也不能证明所有充值同步均正常。发现缺失或滞后时，先核对玩家、链和查询范围，再请平台查同步状态。
玩家提现列表的空 items 只表示当前页没有匹配的已受理记录。每日上限拒单不进入此列表，未知提交也可能尚未进入列表，超出末页也会返回空数组；不能由此释放本地预扣或把原单判为失败。