鉴权、限流与错误

Bearer Token

所有 /api/wgo/v1/ 请求必须携带：

Authorization: Bearer mq_xxx

Token 必须具有 wgo:read 权限。未携带 Token，或者 Token 无效、过期、已吊销、权限不足， 都会返回 401。

Token 的申请和管理方式见 MobiusQuant Token 指南。采集端内部凭证与读取 Token 无关，公开客户端不应接触内部凭证。

请求限流

WGO 默认每个 Token 每分钟 60 次请求。单个 Token 可以配置更低的额度，因此客户端必须 以实际的 429 响应为准，并按 Retry-After 指定的秒数等待。

日报场景建议每个币种先调用一次 overview，只有需要下钻时再请求历史和分基金数据。

错误码

HTTP	含义	处理方式
401	Token 缺失、无效、过期、已吊销或缺少 wgo:read	修正 Token，不要原样重试
422	币种、日期、范围或 limit 不合法	根据 detail 修正请求
429	超出 Token 请求额度	遵守 Retry-After
500–503	服务或数据库暂时不可用	使用有上限的指数退避重试

合法查询没有数据时返回 200 和空 data，或者 observations: 0 的 overview，不返回 404。

日期范围校验

日期格式为 YYYY-MM-DD。同时传入 start 和 end 时，start 不能晚于 end。

{
  "detail": "start must not be after end"
}

安全要求

• 使用环境变量或密钥管理器保存 Token。
• 开发、测试和生产环境使用不同 Token。
• 不要把 Token 写入公开文档、日志、源码或客户端 JavaScript。
• 怀疑泄漏时立即吊销并重新创建 Token。

API 契约

• 在线 Swagger
• 线上 OpenAPI
• 经过构建校验的文档站快照

文档构建会根据线上 OpenAPI 校验公开路径和参数清单，内部采集路由不会进入公开契约。