超时、频率限制与 API Key 安全
本文说明请求超时、频率限制时该怎么处理,以及如何安全地保管 API Key。
超时
- 生成长内容时用流式输出。流式输出(
"stream": true)会边生成边返回,等待时间更短,也更不容易被网络或代理中断。 - 把客户端超时设长一些。非流式请求建议设为 10 分钟以上。Claude Code 可以用
API_TIMEOUT_MS调整,SDK 一般有timeout参数。 - 流式中途超时。服务端在流式输出时约每 10 秒发送一次保持连接的消息;如果上游约 3 分钟没有任何输出,请求会以超时错误结束。这种情况重试即可。
频率限制(429)
返回 429 表示暂时无法处理这个请求,常见原因有:
- 短时间内请求太多,或同时进行的请求太多;
- 上游暂时繁忙;
- 这个 Key 设置的额度已经用完(错误码
API_KEY_QUOTA_EXHAUSTED)。
处理建议:
- 稍等后重试。返回中带有
Retry-After头时,按它给出的秒数等待。 - 在程序里使用「指数退避」重试:第一次等 1 秒,之后每次加倍,并设置最多重试几次。
- 不要同时发出大量并发请求。
- 如果是 Key 额度用完,在控制台调整额度或新建 Key。
保管好 API Key
- 不要写进代码。用环境变量传给程序,不要把 Key 提交到代码仓库,也不要放进前端网页。
- 按用途分开建 Key。不同的工具或设备各用一个 Key,出问题时只需要停用其中一个。
- 注意明文配置文件。Claude Code 的
settings.json等配置文件里的 Key 是明文,不要分享或上传这些文件。 - 发现泄露立即停用。在控制台停用或删除泄露的 Key,再新建一个,并检查使用记录里有没有异常调用。修改登录密码不会让已有的 Key 失效。
- Key 放在请求头里。不要把 Key 写在网址参数中,这种请求会被拒绝。