---
title: WGO 鉴权、限流与错误
description: WGO API 的 Bearer Token 权限、默认限流、错误处理和安全要求。
---

# 鉴权、限流与错误

## Bearer Token

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

```http
Authorization: Bearer mq_xxx
```

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

Token 的申请和管理方式见 [MobiusQuant Token 指南](/zh/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`。

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

## 安全要求

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

## API 契约

- [在线 Swagger](https://api.mobiusquant.ai/api/wgo/docs)
- [线上 OpenAPI](https://api.mobiusquant.ai/api/wgo/openapi.json)
- [经过构建校验的文档站快照](/wgo/openapi.json)

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