SDK 集成故障排除

在升級支持請求之前診斷 Trading Widget、Agent SDK、簽名、webhook、超時和環境問題。

從失敗操作的環境、時間戳和業務標識符開始。結構化檢查通常將配置問題與身份驗證、網絡和異步處理問題分開。

推薦的診斷順序

確認受影響的環境和基地URL。
記錄 UTC 時間範圍和第一個失敗的請求。
識別模塊：Trading Widget、Agent SDK、REST API、WebSocket 或 webhook。
捕獲請求 ID、合作伙伴用戶 ID、agentOrderNo、訂單 ID 或 webhook 事件 ID。
檢查最近的代碼、憑據、IP 白名單或部署更改。
使用最小的安全測試用例進行重現。

症狀	可能的原因	使固定
iframe 請求合作伙伴本地域	baseUrl 缺失	通過baseUrl：‘https://app.6mm.com’。
iframe 不可見或非常短	父容器沒有高度	設置容器高度或通道高度。
token_provider_missing	合作伙伴令牌模式沒有提供商	添加授權。tokenProvider。
auth_exchange_failed	嵌入令牌無效、過期或不匹配	檢查後端令牌響應和 channelId。

Agent SDK 問題

症狀	可能的原因	使固定
簽名被拒絕	錯誤的秘密、時鐘漂移或手動更改的簽名字段	讓 SDK 生成簽名字段並同步服務器時間。
資金重複流動風險	超時後使用新訂單號	先按原文agentOrderNo查詢。
PROCESSING 被視為失敗	待處理狀態被誤解	等待webhook或致電queryOrder。
Webhook 已處理多次	無冪等性的重試行為	添加冪等性密鑰和最終狀態檢查。

需要捕捉的證據

一體化	有用的證據
Trading Widget	頁面 URL、SDK 版本路徑、瀏覽器控制台、失敗的網絡請求、`onError` 負載和容器尺寸。
Agent SDK	SDK 語言/版本、基本 URL、UTC 時間戳、請求 ID、`agentOrderNo`、響應代碼和清理日誌。
Webhook	交付時間、事件或業務密鑰、簽名驗證結果、處理狀態和經過淨化的原始主體哈希。
REST API	方法、路徑、環境、請求 ID、響應代碼和已清理的參數。

切勿在診斷中包含密碼、訪問令牌、API 機密、完整簽名、私鑰或未經編輯的個人數據。

升級之前

僅當該操作被記錄為可以安全重試時才重試。
超時後，查詢原始業務標識符而不是創建新業務標識符。
確認系統時鐘和憑證環境是否存在簽名錯誤。
保留第一次失敗和任何以後重試的結果。
使用支持請求模板發送完整的、經過編輯的報告。

相關文檔

Trading Widget 快速入門

驗證腳本加載、容器大小、配置和回調。

秘密與簽名

檢查 Agent SDK 憑據、時鐘和簽名字段。

Webhooks & 冪等性

檢查回調驗證和重複事件處理。

Java v0.3.0 診斷

症狀	檢查與恢復
資金請求結果未知	保留原來的`agentOrderNo`；使用原始環境調用 `queryWalletTransfer`。不要使用`queryOrder`。
模擬 UI 顯示意外資金	與後端 `environment` 分開檢查前端 `tradingMode`；帳戶 `isSimulatedUser` 不路由請求。
查詢錯誤`6905`	停止使用共享合作伙伴配額，然後重試相同的游標並通過 SDK 進行篩選。
查詢錯誤`6904`	減少併發查詢，縮小時間窗口；如果持續存在，請聯繫支持人員。
游標無效或過期	重新啟動相同的固定歷史窗口並刪除重複的保存記錄。
缺少新的 Java 方法	根據公共標籤 `v0.3.0` 檢查已解析的 Maven 工件；根據您的工件策略刪除衝突的依賴項。

查詢及錯誤參考 · 升級指南

Webhook接收問題

症狀	檢查及處理
返回失敗後不重試JSON	檢查端點是否仍回傳 HTTP 200。投遞僅使用 HTTP 狀態，而非正文中的成功指示符。
401 或 409 後繼續重試	非 2xx 回應遵循現有的重試策略；調查簽名、通知內容或商家配置。
用於清算警告的空冪等鍵	目前的 `WebhookVerifier.idempotencyKey` 僅提取資金事件身分。簽章和所有權檢查後，請驗證 `notificationId` 並在商家程式碼中建立警告金鑰。切勿使用空白鑰匙。
成功處理後重複通知	在商家和 `environment` 範圍內保留重複資料刪除。對於相同的重複項，傳回 2xx；記錄衝突並為具有不同主體的相同 ID 傳回非 2xx。
警告未處理	接受`liquidation.warning`和歷史`LIQUIDATION_WARNING`；不要按使用者、事件或事件類型對不同的通知 ID 進行分組並丟棄它們。
已接受的通知將丟失其待處理任務	返回 2xx 之前可靠地保存任務；啟動記憶體中的非同步任務是不夠的。

事件字段和相容性 · HTTP回應與可靠的確認