服务端 API 常见问题

本页覆盖 Open API 的签名、限频、幂等、回调与数据导出问题。签名算法 sha1(appSecret + nonce + timestamp)，时间窗 ±300 秒，Nonce 5 分钟内不可重复。

返回 1018（签名错误）怎么排查？​

  • 确认签名串顺序：AppSecret + Nonce + Timestamp（拼接后 SHA1，hex 小写）。
  • 确认 Timestamp 是毫秒且与服务器时间偏差在 ±5 分钟内（1019 会提示时间戳超窗）。
  • 确认 Nonce 未重复使用（1020 表示重放）。
  • 确认请求头是 App-Key / Nonce / Timestamp / Signature，且 AppSecret 没有多余空格。

为什么同样的签名第二次调用失败？​

Nonce 在有效期内不可重复（1020）。每次请求都要重新生成 Nonce 与 Timestamp，不要缓存签名。

返回 401/403 是密钥问题吗？​

401 常见于 1018/1019/1020（签名/时间/重放）；403 常见于应用停用（1017）、服务未开通（1021）或管理端角色不足。管理端接口还要求 X-Admin-Secret 或子账号 token。

接口限频了怎么处理？​

超限返回 HTTP 429 + 1008 + Retry-After。按 Retry-After 等待后重试；批量场景请降低并发并合并请求。接口级 QPS 可在控制台「接口调频」按 operationId 设置。

Open API 是幂等的吗？​

部分接口声明幂等（当前 54 个），重复调用等价一次；未声明幂等的接口（创建群/聊天室/标签等）超时后重试可能产生重复数据，需要先查询再决定。

消息发送接口需要 clientMsgId 吗？​

强烈建议传：同一用户 10 分钟内相同 clientMsgId 视为同一条消息，重试不会重复。不传则由服务端生成，重试会产生重复消息。

回调一直重试失败会怎样？​

回调最多投递 3 次（退避 1000/5000/30000ms，单次超时 5000ms）；失败记录在投递日志，可手动重试。持续失败不影响消息投递。

回调验签失败怎么办？​

用原始 body（不要先 JSON.parse 再序列化）参与 HMAC-SHA256：hmac_sha256(secret, timestamp + "." + nonce + "." + rawBody)；同时校验时间窗（±5 分钟）。轮换密钥期间用新旧双密钥验证。

回调会重复吗？会乱序吗？​

会重复（at-least-once），必须用 eventId 去重；同事件类型内近似有序，不保证全局顺序。

如何导出/清理历史消息？​

管理端支持导出 CSV（limit 默认 1000、可带 beforeSeq），清理使用 message.history.clean（可按会话/用户/时间）。清理只影响服务端存储与补发过滤，不影响客户端本地库。

服务端时间与本地不一致会怎样？​

Open API 签名允许 ±5 分钟；超过返回 1019。服务器请启用 NTP；回调时间窗同理。

如何定位一次失败的调用？​

Open API 响应带 requestId：记录 requestId + 接口路径 + appkey + 时间 + 业务单号，服务端日志可按 requestId 检索。客户端 SDK 失败没有 requestId，用错误码 + 时间 + 用户/会话 ID 关联。

相关链接​