BioTech 开放平台文档
简体中文English
输入关键词搜索文档。

调用指南

错误与频控

按 HTTP 状态码处理认证、授权、发布、频控和服务异常。

查看 Markdown在 ChatGPT 中打开在 Claude 中打开

错误响应

json
{
  "code": 403,
  "message": "应用无权访问该接口",
  "data": []
}

外部响应只保证 code、message 和 data。内部审计错误码不会作为 JSON 字段返回，客户端不要假设存在 error_code。

HTTP 状态码

状态常见场景建议处理
401缺少、无效或过期的 Access Token；应用禁用；应用凭证错误尝试刷新一次令牌；失败后停止请求并联系管理员
403应用未获得该接口授权不重试，请管理员检查接口授权
404路由不存在或未使用 OpenAPI 机制发布检查路径和接口发布状态
405路径存在但 HTTP 方法错误使用 Allow 响应头中的方法
422JSON 请求字段缺失、类型或长度不合法修正请求参数后重试
429认证频控、连续认证失败冻结、QPS 或 30 天额度用尽按 Retry-After 延迟重试
500未识别的内部异常记录 X-Request-Id，进行有限次数退避重试
503Redis 频控不可用或接口频控配置缺失记录请求 ID，退避重试并通知平台管理员

401 响应包含 WWW-Authenticate: Bearer。所有 OpenAPI 响应都包含 X-Request-Id，可用于关联平台调用日志。

业务接口频控

频控按 应用 ID + 接口 ID 独立计数，不同应用和接口互不影响。

  • QPS 使用 1 秒固定窗口。
  • 30 天额度从当前计数周期第一次调用开始，周期为固定 2,592,000 秒，不按自然月重置。
  • 默认新接口启用频控，QPS 为 10，30 天总量为 100000；管理员可以修改或关闭。
  • 频控启用时 Redis 不可用会返回 503，不会无限放行。

成功响应可能包含：

响应头说明
X-RateLimit-Statusenabled 或 disabled
X-RateLimit-QPS-Limit每秒上限
X-RateLimit-QPS-Remaining当前秒窗口剩余量
X-RateLimit-30d-Limit当前 30 天周期总量
X-RateLimit-30d-Remaining当前周期剩余量
X-RateLimit-30d-Reset当前周期重置的 Unix 时间戳

频控拒绝还会返回 Retry-After，单位为秒。

认证接口默认限制

下表是插件默认配置，部署环境可以覆盖：

接口或维度默认限制
获取令牌，来源 IP每分钟 10 次
获取令牌，App Key 与来源 IP每分钟 5 次
刷新令牌，来源 IP每分钟 30 次
刷新令牌，Refresh Token 指纹每分钟 10 次
吊销令牌，来源 IP每分钟 30 次

同一凭证连续获取令牌失败达到 5 次后，会从 60 秒开始指数冻结，最长 15 分钟。认证成功会清理对应失败状态。

重试建议

  • 401：只允许一次刷新并重放；刷新失败后要求重新配置凭证。
  • 403、404、405、422：修正配置或请求，不做自动重试。
  • 429：严格等待 Retry-After，并增加少量随机抖动。
  • 500、503：使用有上限的指数退避，并保留 X-Request-Id。
  • 非幂等业务请求在没有业务幂等键时不要自动重放。

日志安全

调用方日志建议记录方法、路径、HTTP 状态、业务 code、耗时和 X-Request-Id。不要记录：

  • App Secret
  • 完整 Access Token 或 Refresh Token
  • Authorization、Cookie
  • 含敏感数据的完整请求体和响应体

最后更新于 2026年8月27日