跳转到主要内容

​
请求限制

​
频率限制

为保证服务稳定性，API 对请求频率有一定限制。当请求过于频繁时，将返回 429 状态码和 RequestTooFrequently 错误。
请合理控制请求频率，避免在短时间内发送大量请求。建议实现重试机制，在收到 429 错误时进行指数退避重试。

​
权限限制

  • 每个 APP Key 继承其创建者的全部权限
  • 操作超出权限范围时，将返回 403 状态码和 AccessDenied 错误
  • 建议为不同用途创建独立的 APP Key，遵循最小权限原则

​
错误码列表

错误码HTTP Status描述
InvalidParameter400参数错误，请检查请求参数是否正确
InvalidContentType400Content-Type 不支持，请使用 application/json
MethodNotAllowed400HTTP Method 不支持
Unauthorized401登录认证未通过，请检查 APP Key 是否正确
AccessDenied403权限认证未通过，当前用户无此操作权限
RouteNotFound404请求 Method + Path 未匹配，请检查 API 地址
RequestTooFrequently429请求过于频繁，请稍后重试
ResourceNotFound400账户未购买资源，请前往费用中心下单
NoLicense400账户无充足订阅 License，请前往费用中心升级或购买订阅
InternalError500内部或未知错误，请联系技术支持

​
错误处理建议

可能原因：
  • 缺少必填参数
  • 参数格式不正确
  • Content-Type 未设置为 application/json
解决方案： 检查请求参数和 Headers 设置，参考 API 文档确认参数要求。
可能原因：
  • APP Key 未提供
  • APP Key 不正确或已失效
解决方案：
  1. 确认请求 URL 中包含 app_key 参数
  2. 前往控制台检查 APP Key 是否有效
可能原因：
  • 当前用户无权执行此操作
  • APP Key 对应用户权限不足
解决方案： 联系账户管理员提升权限，或使用具有相应权限的 APP Key。
可能原因：
  • 短时间内发送了过多请求
解决方案：
  1. 降低请求频率
  2. 实现指数退避重试机制
  3. 合并多个请求（如使用批量接口）
可能原因：
  • 服务端内部异常
解决方案：
  1. 稍后重试
  2. 如持续出现，请联系技术支持并提供 request_id

​
最佳实践

实现重试机制

对于网络错误和 5xx 错误，建议实现指数退避重试，初始间隔 1 秒，最大重试 3 次。

记录 request_id

保存每次请求返回的 request_id，便于问题排查和技术支持。

保护 APP Key

不要在客户端代码中硬编码 APP Key，建议通过环境变量或配置中心管理。

定期轮换密钥

定期更换 APP Key，及时删除不再使用的密钥，降低泄露风险。