SDK 接入问题排查

在提交支持请求前，排查 Trading Widget、Agent SDK、签名、Webhook、超时和环境问题。

排查时先确认环境、时间和失败操作的业务标识。按固定顺序检查，可以快速区分配置、鉴权、网络和异步处理问题。

建议排查顺序

确认受影响环境和 Base URL。
记录 UTC 时间范围以及第一次失败的请求。
确认模块：Trading Widget、Agent SDK、REST API、WebSocket 或 Webhook。
保存 requestId、合作方用户 ID、agentOrderNo、订单 ID 或 Webhook eventId。
检查最近的代码、凭证、IP 白名单或部署变化。
使用最小且安全的测试场景复现。

现象	可能原因	处理方式
iframe 请求 Partner 本地域名	未传 baseUrl	传 baseUrl: ‘https://app.6mm.com’。
iframe 不显示或高度很小	父容器没有高度	设置容器高度或传 height。
token_provider_missing	partner-token 模式没有 provider	补充 auth.tokenProvider。
auth_exchange_failed	token 无效、过期或 channelId 不一致	检查后端返回和 channelId。

Agent SDK 问题

现象	可能原因	处理方式
签名失败	密钥错误、时间漂移或手动改签名字段	让 SDK 自动生成签名字段并同步服务器时间。
有重复资金变动风险	超时后换了新订单号	先用原 agentOrderNo 查单。
把 PROCESSING 当失败	对待确认状态理解错误	等待 Webhook 或调用 queryOrder。
Webhook 重复入账	没有幂等处理	增加幂等键和终态检查。

建议收集的信息

接入类型	有用信息
Trading Widget	页面 URL、SDK 版本路径、浏览器控制台、失败的网络请求、`onError` 内容和容器尺寸。
Agent SDK	SDK 语言与版本、Base URL、UTC 时间、requestId、`agentOrderNo`、响应码和脱敏日志。
Webhook	推送时间、事件或业务键、签名验证结果、处理状态和脱敏后的原始请求体 Hash。
REST API	方法、路径、环境、requestId、响应码和脱敏参数。

诊断信息中不要包含密码、访问令牌、API Secret、完整签名、私钥或未脱敏的个人数据。

提交支持前

只对明确允许安全重试的操作进行重试。
请求超时后查询原始业务标识，不要直接创建新订单号。
签名错误时确认系统时间和凭证环境。
保留第一次失败和后续重试结果。
使用支持请求模板提交完整且已脱敏的问题报告。

相关文档

Trading Widget 快速开始

检查脚本加载、容器尺寸、配置和回调。

密钥与签名

检查 Agent SDK 凭证、时间和签名字段。

Webhook 与幂等

检查回调验证和重复事件处理。

Java v0.3.0 排查

情况	检查与恢复
Funding 请求结果未知	保留原 `agentOrderNo`，通过 `queryWalletTransfer` 按原环境查单，不能使用 `queryOrder`。
模拟页面余额不符合预期	分别检查前端 `tradingMode` 与后端 `environment`，`isSimulatedUser` 不负责请求路由。
查询返回 `6905`	按商户共享额度退避，使用原游标及筛选条件重新调用 SDK。
查询返回 `6904`	降低并发、缩小时间窗口，持续出现时联系支持。
游标非法或过期	重新拉取相同固定历史窗口，幂等保存记录。
Java 新方法不存在	核对 Maven 实际解析制品与公开标签 `v0.3.0`，按制品策略处理依赖冲突。

查询与错误说明 · 升级指南

Webhook 接收排查

现象	检查与处理
返回失败 JSON 后平台没有重试	检查是否仍返回 HTTP 200；平台只看 HTTP 状态码，不解析正文成功标识。
返回 401 或 409 后仍收到重试	非 2xx 会按既有策略重试；排查签名、通知内容或商户配置。
强平预警幂等键为空	当前 `WebhookVerifier.idempotencyKey` 仅提取资金事件身份；验签和归属校验后，自行校验 `notificationId` 并构造预警键，不能使用空串。
处理成功后仍收到同一通知	在商户与 `environment` 范围内持久去重；同正文重复返回 2xx，同 ID 异正文记录冲突并返回非 2xx。
预警被漏处理	兼容 `liquidation.warning` 与历史 `LIQUIDATION_WARNING`；不同通知 ID 不按用户、轮次或事件类型合并丢弃。
业务已确认接收但后续任务丢失	返回 2xx 前必须可靠保存任务，不能仅启动内存异步任务。

事件字段与兼容说明 · HTTP 响应与可靠确认