## 查询取数接入路线

以下是推荐阅读顺序，不代表已完成的进度；可选步骤可以跳过。

1. [获取与使用 API Key](/docs/authentication)
2. [完成第一次查询](/docs/quickstart)
3. [关键词与语义检索](/docs/search)
4. [用户、话题、标签与分类](/docs/browse)（可选）
5. [读取内容与历史](/docs/documents)
6. [下载图片与附件](/docs/attachments)（可选）
7. [限流、重试与排错](/docs/production) ← 当前页

**开始前**：查询与读取已跑通，准备接入持续运行的应用。

# 限流、重试与排错

## 请求失败先查什么

先记录 HTTP 状态、响应中的 `code`、请求 ID（如有）和不含密钥的请求条件。下面按状态码给出检查顺序；具体错误码与恢复方式以对应接口文档为准。

| HTTP | 优先检查 | 下一步 |
| --- | --- | --- |
| 400 | 必填字段、枚举、时间窗口、游标与筛选组合是否有效 | 对照[搜索](/docs/search)或[筛选](/docs/browse)修正请求，不原样重试 |
| 401 | 是否使用有效 Consumer API Key，Bearer 格式是否正确 | 按[密钥说明](/docs/authentication)检查凭据，不在日志输出 Key |
| 403 | 数据集、平台、字段及采集能力是否获批 | 请你的组织管理员检查[应用订阅](/docs/portal)，生成新 Key 不会扩大权限 |
| 404 | Whale `document_id` 或平台用户 ID 是否正确 | 核对 ID；[用户资料](/docs/browse#读取用户资料与用户内容)在窗口内无可授权观察时也可能不存在 |
| 409 | 按需采集结果是否尚未落库 | 按[实时结果读取规则](/docs/live-query#轮询与读取结果)等待并有限重试，不重复创建查询 |
| 410 | 增量同步游标是否超出保留窗口 | 按[增量同步恢复规则](/docs/change-feed#错误处理)重新建立基线 |
| 429 | 触发速率、并发限制还是日配额 | 检查响应 `code` 和 `Retry-After`，降低并发或等待配额重置 |
| 502 / 503 / 504 | 网关或依赖服务是否暂时不可用 | 对安全读取有限退避重试；创建任务时先确认是否已成功，避免重复创建 |

`batch-get` 的 HTTP 成功不代表每条内容都成功；逐条检查 `error`。异步采集的 `queued` 也不代表数据已可读取。

## 查询为空怎么办

1. 确认环境地址、应用订阅、数据集和平台是否正确；空结果不证明平台上不存在该内容。
2. 缩减关键词或筛选条件，检查发布时间与入库时间是否混淆。[筛选与用户接口](/docs/browse)默认查询最近 24 小时的首次入库数据，单次窗口最多 31 天。
3. 用户资料是窗口内最新入库内容附带的作者观察值，不是平台用户的实时全量资料。
4. 需要新采集的数据时，先确认[按需采集授权](/docs/live-query)；不要仅因搜索为空就自动创建收费采集任务。

## 建议默认值

| 项目 | 建议 |
| --- | --- |
| 连接超时 | 3 秒 |
| 检索请求超时 | 15 秒 |
| 文档详情超时 | 10 秒 |
| 最大重试 | 3 次 |
| 退避 | 指数退避加随机抖动，起始 500 ms |
| 批量详情 | 每批最多 50 个 `document_id` |

安全读取可对网络失败、`429`、`502`、`503`、`504` 有限重试。不要自动重试 `400`、`401` 和 `403`。创建任务或订阅等写操作不能直接套用读取重试策略，应先确认请求结果及接口的幂等约定。

## 429 处理

优先读取 `Retry-After`：


```text
delay = max(Retry-After, exponential_backoff) + random_jitter
```


应用应限制本地并发并复用 HTTP 连接。`quota_exceeded` 表示日配额耗尽，短间隔重试无法恢复，应等待 UTC 配额窗口重置或申请调整。

## 查询范围

- 首次接入使用明确平台和较小发布时间窗口。
- 列表场景先搜索或按条件筛选，再使用 `batch-get` 批量补齐详情。
- 只有详情或导出场景读取完整正文、字幕和历史快照。
- 支持游标的接口使用其返回的游标，并保持该接口要求固定的查询条件；不要自行构造游标或数据库偏移量。
- 向量与混合检索不支持 cursor，不适合全量导出。正文版本和指标快照只支持限量读取（最多 500），不能靠重复请求遍历全部历史。详见[搜索分页](/docs/search#分页)和[历史读取限制](/docs/documents#查看正文版本历史)。

## 兼容性

- `document_id`、`dataset_id`、`source_platform` 和枚举值是稳定协议字段。
- 客户端必须忽略未知响应字段，平台可能以向后兼容方式增加字段。
- 删除或改变字段语义需要新的 API 版本及迁移窗口。

## 检查与继续

**完成标准**：已配置超时、限流退避与重试，并选择持续同步、实时采集或 SDK/MCP 接入方式。

上一步：[下载图片与附件](/docs/attachments)

**接入路线已读完**。满足上面的检查后，再按目标选择扩展功能。

**可选任务**

- [增量同步数据](/docs/change-feed)
- [批量导出数据](/docs/exports)
- [按需采集新数据](/docs/live-query)
- [定期采集用户与频道](/docs/collection-subscriptions)
- [查询 SDK（Python 与 Go）](/docs/sdk)
- [MCP 接入](/docs/mcp)
- [应用与订阅管理](/docs/portal)
- [平台覆盖与能力](/docs/platforms)