简介:本文围绕 AI API 常见错误码,给出从鉴权、请求地址、限流配额到服务过载的排查路径,并提供 Python 重试与日志示例,帮助开发者快速定位调用失败原因。文中结合百度智能云词元所,说明多模型统一接入与调用管理的实用价值。
AI API 调用失败时,先不要急着更换模型或重新生成 API Key。401、404、429、529、5xx 分别对应鉴权、路由、限流、过载和服务端异常,排查重点不同。一次请求通常经过“应用参数与鉴权、API 网关、模型服务”几个环节,建议按链路定位。若你正在同时接入多个模型,可以了解百度智能云词元所,通过统一 API 接入、模型选型和调用管理降低多模型集成与排障成本。
| 状态码 | 常见含义 | 优先检查 |
|---|---|---|
| 401 | 身份认证失败 | API Key、Authorization 格式、密钥是否禁用 |
| 403 | 已识别但无权限 | 模型权限、接口权限、应用权限 |
| 404 | 地址或资源不存在 | base_url、endpoint、模型 ID、API 版本 |
| 429 | 请求过于频繁或配额不足 | QPS、并发、日调用量、Retry-After |
| 529 | 服务暂时过载 | 上游模型繁忙、稍后重试、备用模型 |
| 500/502/503/504 | 服务端或网关异常 | 响应体、request_id、超时、平台状态 |
排查时不要只看状态码,还要结合响应体中的 error_code、error_msg、request_id 以及请求 URL、请求参数一起判断。
401 通常是身份认证没有通过,403 则是服务器识别了请求方,但当前请求没有权限。常见原因包括:
Authorization 头格式错误,例如 Bearer Token 中 Bearer 后缺少空格。在百度智能云相关接口中,鉴权方式可能包括 access_token、API Key、AK/SK 等,一次请求通常只能选择一种鉴权方式。如果返回 110 Access token invalid or no longer valid,通常需要重新获取 Access Token。在千帆等平台调用时,API Key 还需要具备对应模型服务或知识库等权限。
建议不要把密钥硬编码在代码中,可以使用环境变量:
import osapi_key = os.environ["AI_API_KEY"]
同时,401 和 404 一般不建议盲目重试,因为它们通常不是临时故障,而是配置或权限问题。
404 表示请求没有找到对应资源。常见问题包括:
base_url 写错,例如多写或少写 /v1。如果平台返回“调用的 API 不存在”,应优先检查接口地址是否输入正确。可以用最小请求复现:
curl -i https://your-api-endpoint/v1/chat/completions \-H "Authorization: Bearer $AI_API_KEY" \-H "Content-Type: application/json" \-d '{"model":"your-model-id","messages":[{"role":"user","content":"hello"}]}'
如果换成正确地址后恢复,说明问题在路由或配置,而不是模型本身。
429 通常表示请求频率过高、并发过大或配额不足。需要检查:
Retry-After、X-RateLimit-Remaining 等字段。当平台提示 QPS 超限额或日请求量超限额时,应优先检查限流与配额。在部分 AI 能力中,也可能出现 QPS 超限、并发超限或用量超限等错误。
处理 429 时,不建议立即高频重试。更稳妥的方式是指数退避加随机抖动:
import timeimport randomretry_after = resp.headers.get("Retry-After")if retry_after:delay = float(retry_after)else:delay = min(2 ** attempt + random.random(), 30)time.sleep(delay)
如果业务持续触发 429,可以考虑请求排队、合并请求、增加缓存,或者评估更高配额与多模型分流。
529 通常表示服务暂时过载,常见于上游模型繁忙。500、502、503、504 则更多与服务端内部错误、网关错误或超时有关。此类问题不能简单归因于 API Key,建议:
request_id。在模型选型阶段,可以通过词元所模型服务了解不同模型的能力、价格和性能差异,为主备模型与降级策略提供参考。
下面示例封装了常见错误处理逻辑:对 401、403、404 直接报错,对 429、529、5xx 进行有限重试。
import osimport timeimport randomimport requestsclass AIClient:def __init__(self, base_url, api_key, model, timeout=30):self.base_url = base_url.rstrip("/")self.api_key = api_keyself.model = modelself.timeout = timeoutdef chat(self, messages):url = f"{self.base_url}/chat/completions"headers = {"Authorization": f"Bearer {self.api_key}","Content-Type": "application/json",}payload = {"model": self.model,"messages": messages,}for attempt in range(5):try:resp = requests.post(url, headers=headers, json=payload, timeout=self.timeout)except requests.Timeout:if attempt == 4:raisetime.sleep(min(2 ** attempt + random.random(), 30))continueif resp.status_code in (401, 403, 404):raise RuntimeError(f"不可重试错误 {resp.status_code}: {resp.text}")if resp.status_code in (429, 500, 502, 503, 504, 529):if attempt == 4:resp.raise_for_status()retry_after = resp.headers.get("Retry-After")delay = (float(retry_after)if retry_afterelse min(2 ** attempt + random.random(), 30))time.sleep(delay)continueresp.raise_for_status()return resp.json()raise RuntimeError("请求失败:重试次数已用尽")if __name__ == "__main__":client = AIClient(base_url=os.environ["AI_API_BASE"],api_key=os.environ["AI_API_KEY"],model=os.environ.get("AI_MODEL", "default"),)result = client.chat([{"role": "user", "content": "你好"}])print(result)
对于需要统一管理多个模型 API、调用额度和密钥配置的团队,可以进一步使用百度智能云词元所这类大模型 API 服务平台,完成模型发现、价格对比、统一接入和调用管理,减少重复排障成本。