> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rockapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API 接入最佳实践：超时、重试、幂等与限流检查清单

> 从成功测试走向生产接入，逐项检查超时预算、重试安全、幂等、速率与额度限制、流式响应和灰度发布。

一次测试成功只能证明链路可用。生产接入还要明确上游变慢、响应丢失、流量超限和重复提交时的行为。在扩大流量之前确定这些规则，因为失败调用和重复操作既可能增加费用，也可能让用户无法判断操作是否完成。

## 先核对一个请求及其边界

确认选定服务的基础 URL、端点、鉴权方式、必填字段、响应格式和计费单位。市场内的服务可能各有契约，不能假设所有 API 都使用 AI 网关的地址或请求格式。市场接入流程可参考 [订阅并在线测试 OpenAPI](https://docs.rockapi.ai/zh-cn/blog/buyers/how-to-subscribe-and-test-openapi.md)。

密钥放在服务端的密钥管理系统或环境配置中。区分开发与生产凭据，对应用日志中的鉴权头做脱敏。保留一份脱敏后的成功请求及应用依赖的响应字段，作为接入基准。

## 同时设置超时和重试预算

分别设置连接超时、响应读取超时和整个操作的截止时间。流式请求还应设置空闲超时。根据实测耗时和用户可等待的时间选择参数。例如，对短操作可先试验连接超时 5 秒、总时限 30 秒、最多重试两次；这些只是示例配置，并非 Rock API 默认值。

| 信号 | 应用应采取的动作 |
| - | - |
| `400` 或校验失败 | 修正请求，不要原样重试。 |
| `401` 或 `403` | 检查凭据、权限和订阅，停止自动重试。 |
| `429` | 区分速率限制与额度耗尽，降低并发并查看响应说明。 |
| 临时 `5xx` 或网络故障 | 仅在重复操作安全且剩余时限允许时重试。 |

使用带随机抖动的指数退避；服务返回 `Retry-After` 时按其要求等待。限制总尝试次数和总耗时，同时检查 SDK、代理与任务消费者的重试设置，避免多层重试叠加放大流量。

## 显式处理结果不确定的操作

超时不代表服务端拒绝了请求。重复 POST 可能创建第二份资源、再次生成内容或再次计费。仅在端点文档明确说明支持范围和保留时间时使用幂等键；随意添加一个请求头不能获得幂等保证。

若无明确支持，应保存本地操作 ID，并通过文档提供的状态查询或用量记录核对结果，再决定是否重复敏感操作。流式响应需要测试分片、断连、取消和结束标记。重新发送已经返回部分结果的生成请求，可能产生不同内容和额外用量。

## 验证限额并逐步放量

使用有界队列和每服务并发上限。分别处理请求速率与 token、字符、每日或每月额度。监控剩余额度和余额，不要把所有 `429` 都理解为需要升级套餐。

在安全环境中测试无效凭据、错误输入、额度耗尽、延迟响应、流中断和重复提交。先小范围上线，明确回滚条件。记录请求 ID、状态、耗时、重试次数和最终结算用量，避免记录私密载荷。成本和 P95 延迟符合验收阈值后，再增加流量。

> [card] [检查 AI API 安全与隐私](https://docs.rockapi.ai/zh-cn/blog/buyers/ai-api-security-privacy.md)
>
> 上线前评估数据流向、保留条款、凭据管理和事件处理流程。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.