限流、重试与排错

请求失败先查什么

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

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

查询为空怎么办

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

建议默认值

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

429 处理

优先读取 Retry-After：

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

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

查询范围

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

兼容性

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