生产调用规范

建议默认值

只对网络失败、429、502、503、504 重试。不要自动重试 400、401 和 403。

429 处理

优先读取 Retry-After：

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

应用应限制本地并发并复用 HTTP 连接。短时间创建大量连接会浪费订阅配额并降低有效吞吐。

查询范围

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

兼容性

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