前置条件
已创建应用并保存 AppKey/AppSecret;已能发起请求;可查看开放平台调用日志。
排查顺序
- 401 未认证:核对 AppKey 是否存在、AppSecret 是否正确、签名算法是否为 HMAC-SHA256。
- 时间戳错误:校准服务器时间,确保在允许的时间窗口内;不要缓存旧时间戳。
- 随机串重复:每次请求生成新的随机串,防重放校验会拒绝重复值。
- 403 无权限:检查 IP 白名单、应用是否开通对应接口、账号是否完成实名。
- 404 路径错误:确认接口版本与路径,开放平台使用独立网关,路径与主站页面不同。
- 409 幂等冲突:同一幂等键已处理过,先查询原请求结果,不要更换键重复提交。
- 429 限流:查看配额与令牌桶状态,按建议退避重试。
- 5xx:先重试一次并记录请求 ID,持续失败提交工单,附时间、接口与请求 ID。
结果验证
修正后请求返回 200;调用日志显示成功记录;错误响应中只有错误码与可读消息,不含内部成本信息。
出问题怎么办
- 签名串含中文或特殊字符:确认编码方式与文档一致,避免多次 URL 编码。
- 代理或网关改写请求:确认请求体未被压缩或改写,签名使用原始内容。
- 密钥疑似泄露:立即重置 AppSecret,旧密钥失效后更新服务端配置。
- 无法判断原因:保存完整请求头(脱敏密钥)与响应,提交工单。
常见报错与处理
401 签名错误 原因:签名串顺序错误、密钥错误或请求体被改写。
处理:按文档逐项比对,使用原始请求体签名。
403 IP 不在白名单 原因:服务器出口 IP 变化或未配置。
处理:在开放平台更新白名单,固定出口 IP。
429 频繁限流 原因:并发过高或重试策略不当。
处理:降低并发,使用指数退避,批量场景申请更高配额。