---
title: 生产调用规范
description: 外部客户端的超时、重试、并发和兼容性约束。
---

# 生产调用规范

## 建议默认值

| 项目 | 建议 |
| --- | --- |
| 连接超时 | 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 连接。短时间创建大量连接会浪费订阅配额并降低有效吞吐。

## 查询范围

- 首次接入使用明确平台和较小发布时间窗口。
- 列表场景先检索，再使用 `batch-get` 批量补齐详情。
- 只有详情或导出场景读取完整正文、字幕和历史快照。
- 分页和增量同步必须使用接口返回的稳定游标，不要自行拼接数据库偏移量。

## 兼容性

- `document_id`、`dataset_id`、`source_platform` 和枚举值是稳定协议字段。
- 客户端必须忽略未知响应字段，平台可能以向后兼容方式增加字段。
- 删除或改变字段语义需要新的 API 版本及迁移窗口。
- 当前验证环境不提供正式 SLA；生产 SLA、域名和维护窗口以商务交付为准。