SureLink 開放平台

錯誤碼字典與排障速查 ​

在與 SureLink 網關對接過程中，若請求發生異常，網關將返回標準 HTTP 狀態碼及統一格式的 JSON 錯誤報文。

1. 統一錯誤回應格式 ​

所有非 2xx 異常回應均遵循以下標準 JSON 結構：

json
{
  "statusCode": 401,
  "errorCode": "MERCHANT_API_UNAUTHORIZED",
  "message": "unauthorized"
}

2. 全域錯誤碼字典 ​

HTTP 狀態碼錯誤碼 (errorCode)預設提示資訊根本原因與排查建議
401MERCHANT_API_UNAUTHORIZEDunauthorized介面鑑權失敗：
1. 缺少必要請求頭（X-Api-Key, X-Timestamp, X-Nonce, X-Signature）；
2. 時間戳超出伺服器當前時間 $\pm 5$ 分鐘；
3. Nonce 長度不在 16~64 位或在 10 分鐘內發生重複；
4. API Key 不存在、已被停用或撤銷；
5. HMAC 簽名計算不符合。
403IP_NOT_WHITELISTEDclient IP is not in merchant IP whitelistIP 白名單攔截：發起請求的伺服器公網出口 IP 未加入商戶安全白名單中。
404ORDER_NOT_FOUNDorder not found訂單不存在或租戶不符合：平台中未找到該訂單，或該訂單屬於其他商戶。
400PAYOUT_DISPUTE_REASON_REQUIREDdispute requires a reason缺少爭議原因：調用代付裁決介面發起 DISPUTE 時，未填寫必填項 reason。
400BAD_REQUEST(欄位詳細校驗資訊)請求參數校驗失敗：例如金額格式非法（如法幣非兩位小數、數位資產超過六位小數）、缺少必填欄位等。
409CONFLICTresource conflict業務衝突：例如使用相同商戶單號並發重複下單但請求參數衝突。
503SERVICE_UNAVAILABLEservice temporarily unavailable網關維護或降級：平台正在執行停機維護，或訂單域功能開關暫時關閉。
500INTERNAL_SERVER_ERRORinternal server error網關內部異常：伺服器臨時故障，請攜帶 requestId 聯繫技術支援。

3. 常見排障排查清單 (Checklist) ​

3.1 簽名不符合 (MERCHANT_API_UNAUTHORIZED) 排查秘籍 ​

90% 以上的聯調鑑權失敗均由此引起，請按以下步驟逐一排查：

  1. Raw Body 拼接差異：
    • 是否在計算簽名時使用了序列化後的字串，而在發送請求時被 HTTP 客戶端重新排版了 JSON（例如增加了空格或換行）？
    • 正確做法：確保簽名使用的字串與 HTTP 傳輸中通過 Socket 發出的 Payload 完全一致（位元組層級相同）。
  2. GET 請求或空 Body 處理：
    • GET 請求時，待簽名串末尾必須包含英文句點：${timestamp}.${nonce}.，不可漏掉最後的 .。
  3. Secret 是否準確：
    • 確認使用的是當前 API Key 對應的最新 API Secret，且兩端無多餘的前後空格。
  4. Hex 格式大小寫：
    • 簽名計算結果必須輸出為 全小寫的 64 位 Hex 字串。

3.2 時間戳超出窗口 (Timestamp Out of Window) ​

  • 網關強制校驗客戶端時間戳與伺服器時間偏差在 300 秒（5分鐘） 以內。
  • 排查方法：檢查商戶調用端伺服器是否開啟 NTP 時間同步（如 ntpdate / chrony）。
  • 注意：X-Timestamp 必須是 毫秒級時間戳（13位數字，如 1715000000000），切勿傳入秒級時間戳（10位）。

3.3 隨機數重放衝突 (Nonce Replay) ​

  • X-Nonce 在同一個 API Key 下在 600 秒內全域唯一。
  • 排查方法：請使用高強度的偽隨機數生成器（如 Node.js crypto.randomBytes(16).toString('hex') 或 Python secrets.token_hex(16)），切勿使用固定值或單純按數字自增遞增（在多實例並發時極易衝突）。

3.4 IP 白名單攔截 (IP_NOT_WHITELISTED) ​

  • 商戶在後台配置了 IP 白名單，但調用請求被攔截。
  • 排查方法：
    1. 很多雲端廠商（如 AWS、阿里雲）的伺服器公網出口 IP 經過了 NAT 網關或代理，可能與伺服器綁定的 EIP 或內網 IP 不同。
    2. 可以在商戶伺服器上執行 curl https://api.ipify.org 查詢伺服器對外展示的真實公網 IP，並將其配置到商戶後台白名單中。