公告 新用户注册即享 免费 SSL 证书 · 域名批量查询单次支持 40 个 · 香港与内地节点均可自助开通
解决方案 帮助中心 关于我们
代理合作 控制台 登录 免费注册

API 签名失败与常见错误码排查

按 401、403、404、409、429、5xx 分类说明开放 API 常见错误的原因、排查顺序与处理方式。

前置条件

已创建应用并保存 AppKey/AppSecret;已能发起请求;可查看开放平台调用日志。

排查顺序

  1. 401 未认证:核对 AppKey 是否存在、AppSecret 是否正确、签名算法是否为 HMAC-SHA256。
  2. 时间戳错误:校准服务器时间,确保在允许的时间窗口内;不要缓存旧时间戳。
  3. 随机串重复:每次请求生成新的随机串,防重放校验会拒绝重复值。
  4. 403 无权限:检查 IP 白名单、应用是否开通对应接口、账号是否完成实名。
  5. 404 路径错误:确认接口版本与路径,开放平台使用独立网关,路径与主站页面不同。
  6. 409 幂等冲突:同一幂等键已处理过,先查询原请求结果,不要更换键重复提交。
  7. 429 限流:查看配额与令牌桶状态,按建议退避重试。
  8. 5xx:先重试一次并记录请求 ID,持续失败提交工单,附时间、接口与请求 ID。

结果验证

修正后请求返回 200;调用日志显示成功记录;错误响应中只有错误码与可读消息,不含内部成本信息。

出问题怎么办

  • 签名串含中文或特殊字符:确认编码方式与文档一致,避免多次 URL 编码。
  • 代理或网关改写请求:确认请求体未被压缩或改写,签名使用原始内容。
  • 密钥疑似泄露:立即重置 AppSecret,旧密钥失效后更新服务端配置。
  • 无法判断原因:保存完整请求头(脱敏密钥)与响应,提交工单。

常见报错与处理

401 签名错误 原因:签名串顺序错误、密钥错误或请求体被改写。

处理:按文档逐项比对,使用原始请求体签名。

403 IP 不在白名单 原因:服务器出口 IP 变化或未配置。

处理:在开放平台更新白名单,固定出口 IP。

429 频繁限流 原因:并发过高或重试策略不当。

处理:降低并发,使用指数退避,批量场景申请更高配额。