瞬时并发
批量任务同时启动可能超过令牌或模型并发限制。
先把三个关键变量分开
同一个错误可能由不同层级触发。按地址、认证、模型或并发逐层验证，比同时修改所有配置更容易定位原因。
持续速率
每分钟请求数或 Token 数超过限制，需要排队或降低吞吐。
资源状态
余额不足、分组不可用或上游号池繁忙也可能通过业务错误体现。
三步完成最小验证
保留一个可复现的短请求，每次只修改一个变量，并记录返回状态。
保存失败样本
记录时间、模型、状态码和请求 ID，不保存 API Key 或敏感输入。
把并发降到 1
用短请求验证单次调用；若成功，再逐级恢复并发。
使用有限退避
对可重试错误采用指数退避和随机抖动，并设置最大次数与总时长。
有限指数退避示例
import random, time
max_attempts = 5
for attempt in range(max_attempts):
try:
result = call_model()
break
except RateLimitError:
if attempt == max_attempts - 1:
raise
delay = min(2 ** attempt, 16) + random.random()
time.sleep(delay)API Key 只放在环境变量或客户端密钥字段中，不要写进公开仓库、截图或前端代码。模型名与价格请从 LinkAGI 实时模型广场复制。
结果出现后，下一步看什么
不要把所有失败都归因到“中转站不稳定”。先判断请求停在路径、认证、模型、速率还是超时层。
单请求成功、并发失败
主要矛盾在并发或速率，使用队列、信号量和更平滑的任务调度。
所有模型都失败
检查账户余额、令牌状态和站点公告，不要只盯某一个模型。
只有一个模型失败
查看该模型的分组、号池和当前状态，必要时选择经过验证的替代模型。
重试后费用异常
确认失败请求是否产生用量，并在调用日志中核对，不用客户端估算替代账单。
LinkAGI 场景
使用 api.linktoagi.com 接入后，可以在控制台调用日志中核对模型、Token、状态和扣费；遇到持续异常可携带时间与请求信息联系支持，但不要发送完整 API Key。
常见问题
429 是否一定是上游问题？
不一定。客户端自身限额、账号余额、令牌限制和中转层并发都可能产生 429 或相似业务错误。
可以一直重试直到成功吗？
不建议。无限重试会放大拥塞和成本，应设置最大次数、总时长与不可重试条件。
流式输出能解决 429 吗？
不能。流式影响响应传输方式，不会提高请求速率或并发额度。
继续排查相关问题
AI API 504 Gateway Timeout
AI API 返回 504：上游没坏，也可能卡在首字节和代理超时
504 表示某一层网关没有在规定时间内拿到下游响应。上游控制台显示正常，并不能排除单请求首字节过慢、边缘代理超时、非流式长任务或客户端提前断开。
OpenAI API 中转站OpenAI API 国内接入：Base URL、Key 与首次请求一次配置
如果现有代码已经使用 OpenAI SDK，迁移到 LinkAGI 通常只需要替换 Base URL 与 API Key。真正容易出错的不是代码主体，而是地址层级、模型名和密钥分组。
Codex 401 Invalid tokenCodex 返回 401：先别改模型，认证链路才是第一现场
401 通常说明域名、HTTPS 和接口路由已经可达，请求停在认证阶段。它不能证明模型可用，但能帮助你把排查范围缩小到 API Key、环境变量和令牌状态。
先用短请求验证 LinkAGI
注册赠送 ¥0.2 试用额度；模型、号池和价格以实时页面为准。