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，并将其配置到商户后台白名单中。