除錯
@moosehq/provider-sdk 內建幾項選用的除錯輔助功能——除非你自己接上，否則都不會執行，也不會引入任何執行期相依套件。本頁涵蓋其中三項；確切型別簽名見 @moosehq/provider-sdk 參考文件，第四項（完全不需要網路就能跑你的接入）見用 createMockPlatform 測試。
診斷無法解釋的 401
401 幾乎都代表平台重新計算出的簽名跟你送出的不一樣——完整契約見簽名與鑑權。explainSignature 的計算方式與 signRequest 完全相同，但同時會返回它所雜湊的原始 canonical string，讓你可以拿去跟平台日誌裡對同一個請求算出來的值做比對：
import { explainSignature } from '@moosehq/provider-sdk'
const explanation = explainSignature({ method: 'POST', path: '/v1/wallet/balance', tenantId, secret, body, now: new Date(), nonce })
console.log(explanation.canonicalString) // "POST\n/v1/wallet/balance\n<ts>\n<nonce>\n<body>"
console.log(explanation.signature)canonicalString 對不上，通常代表實際送出的請求主體跟被簽名的那份不是逐位元組一致（例如 JSON 被重新序列化過、鍵值順序或空白不同），或是 path 帶了不該有的查詢字串。canonicalString 對得上但簽名不同，代表金鑰本身錯了。PlatformApiError.hint（見下方）在真正發生 401 時會自動給出同樣的提示——不是每次失敗都需要動用 explainSignature，只有當 hint 本身還不夠定位問題時才需要。
觀察請求與重試
ProviderClient 預設會靜默重試網路錯誤、409 和 5xx——這正是這個 SDK 的用意所在，但也代表一個緩慢或不穩定的整合，表面上看起來像什麼都沒發生。onDebug 會針對每一次對外請求、回應和重試收到一個 DebugEvent：
const client = new ProviderClient({
baseUrl, tenantId, secret,
onDebug: (event) => {
if (event.phase === 'retry') {
console.warn(`retrying ${event.path} (attempt ${event.attempt}): ${event.reason}`)
} else {
console.debug(event)
}
},
})如果你遇到間歇性的 401 卻找不到其他明顯原因，response 事件的 clockSkewMs（客戶端自己的時鐘減去平台 Date 響應頭）值得留意——伺服器或容器時鐘偏移是一個常見、但平常完全看不到的元兇,因為平台會拒絕一個跟自己時鐘偏差過大的簽名時間戳。
讀懂丟出的錯誤
PlatformApiError 除了 status/body 之外,還帶了三個專門用來縮短除錯迴圈的欄位:
try {
await client.submitTransaction(req)
} catch (err) {
if (err instanceof PlatformApiError) {
console.error(err.status, err.hint)
if (err.requestId) console.error('把這個交給平台支援:', err.requestId)
if (err.retryAfter) console.error('平台要求等待:', err.retryAfter)
}
}requestId 對應平台的 X-Request-Id 響應頭——這是交給平台支援最有用的單一資訊,讓對方能直接在伺服端日誌裡找到這個確切的請求,而不需要你描述時間點或請求內容。hint 是針對該狀態碼最可能原因的一句話提示(並非窮舉,只是一個起點)。完整狀態碼參考見錯誤碼與重試。
不依賴完整平台環境跑測試
目前每一個整合測試都需要完整的 Postgres/Redis/platform/operator 環境跑起來——除非你使用 createMockPlatform,它是平台錢包/RGS 端點的可簽名記憶體模擬實作。完整走查見用 createMockPlatform 測試。