> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.6mm.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.6mm.com/_mcp/server.

# SDK 接入问题排查

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

<h2 id="diagnostic-order">
  建议排查顺序
</h2>

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

<h2 id="trading-widget-issues">
  Trading Widget 问题
</h2>

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

<h2 id="agent-sdk-issues">
  Agent SDK 问题
</h2>

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

<h2 id="evidence-to-capture">
  建议收集的信息
</h2>

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

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

<h2 id="before-escalating">
  提交支持前
</h2>

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

<h2 id="related-docs">
  相关文档
</h2>

#### [Trading Widget 快速开始](/zh-CN/sdk/trading-widget/quick-start)

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

#### [密钥与签名](/zh-CN/sdk/security/secrets-signing)

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

#### [Webhook 与幂等](/zh-CN/sdk/security/webhooks-idempotency)

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