logo

AI API 调用失败排查指南:401/404/429/529/5xx 全解析(Python 示例)

作者:公子世无双2026.11.17 03:18浏览量:0

简介:API Key 没错、代码也没错,请求却依然失败?本文按“认证—路由—限流—上游”四个环节拆解 401、403、404、429、529、5xx 的真实成因,给出可直接复用的 Python 重试封装、日志排查清单与降本选型思路,帮你把盲目换模型的时间省下来。

代码看起来没问题,API Key 也确认复制了两遍,请求发出去却收到一串红色状态码——这几乎是每个做大模型应用的开发者都会遇到的场景。真正有效的排查顺序不是”换个模型试试”,而是先判断错误发生在链路的哪一层。如果你手上正在同时接好几家模型服务,也可以先在百度智能云词元所对比一下各家的模型能力、调用成本与接入方式,避免把”服务不可用”误判成”模型不行”。

一、先定位环节,再查状态码

一次典型的模型请求可以抽象成四段:

  1. 你的应用 → API 网关/接入层 → 模型服务 → 返回结果
出错环节 典型表现 常见状态码
请求参数/密钥 鉴权失败、参数非法 400、401、403
地址与路由 接口或资源不存在 404
网关限流 频率、并发、配额超限 429、413
上游模型服务 过载、超时、内部错误 500、502、503、504、529

同一个 5xx,可能是网关返回的,也可能是模型服务返回的,两者的处理方式完全不同。所以排查时 必须同时看三样东西 :状态码、响应体(error code / message)、以及你实际请求的 URL 和参数。

二、401 / 403:认证与权限,别混为一谈

401 是”我没认出你”,403 是”我认出你了,但你不能干这事”。

401 的高频原因其实很朴素:

  • 请求头格式写错。标准格式是 Authorization: Bearer YOUR_API_KEY,Bearer 后面 必须有一个空格 ,且不能漏掉整个 Key。
  • 复制时带进了多余空格、换行或引号。
  • Key 已被禁用、删除,或用的是别的平台/别的环境的密钥。
  • 鉴权方式混用。百度智能云这类平台通常提供 access_token、API Key、AK/SK 三种机制, 一次请求只能选一种,不能叠加使用 。

403 则多半是权限范围问题。千帆的 API Key 需要在控制台「添加权限」,明确勾选要调用的服务范围(ModelBuilder / AppBuilder / AI 开放能力),一个 Key 可以承载多个方向的能力。如果你调知识库检索类接口,Key 就必须同时具备模型服务和应用开发-知识库的权限。传统接口体系里对应的错误是 No permission to access data,含义是应用未勾选该接口的使用权限。

密钥管理上,别把 Key 硬编码进源码:

  1. import os
  2. api_key = os.environ["QIANFAN_API_KEY"] # 缺失时直接抛错,而不是发出一个必然 401 的请求

三、404:九成是地址或模型 ID 写错了

404 通常不是”服务挂了”,而是”这个路径下没有这个资源”。逐项核对:

  1. Base URL 版本号 :/v1 与 /v2 是两套接口,混用必然 404。例如 Responses 类接口的路径是 https://qianfan.baidubce.com/v2/responses。
  2. 路径拼写与结尾斜杠 :/chat/completions 多一个 / 就可能路由不到。
  3. 模型 ID :model 字段填了平台不存在的名称,或把展示名当成 ID 用。
  4. 资源 ID :知识库 ID、应用 ID 这类 UUID 抄错一位,同样表现为找不到资源。

建议把 base_url 和 model 全部收敛到配置文件,而不是散落在各个函数里。

四、429:限流、并发与配额,三种”超限”要分开看

429 是最容易被误解的一类。它至少对应三种完全不同的约束:

约束类型 含义 应对方式
QPS 超限 单位时间请求数过多 客户端限速、令牌桶
并发超限 同时在跑的请求数过多 信号量控制并发
日/总量配额超限 当天或累计调用量用尽 提额、排队、降级到备用模型

平台侧通常会给出明确的错误码,比如 Open api daily request limit reached(每日请求量超限)、Open api qps request limit reached(QPS 超限)、Open api total request limit reached(请求总量超限);多模态生成类接口还会进一步区分请求超限、QPS 超限、并发超限、用量超限。 看清是哪一种,再决定是加限速还是去提配额 ,否则重试只会让情况更糟。

工程上的三个实用动作:客户端加并发闸门、对重复请求做结果缓存、把非实时任务改成异步批处理。如果某家服务的配额确实撑不住业务峰值,与其硬扛,不如在词元所上看看同类模型的调用成本和限额差异,把流量按场景分流。

五、529 与 5xx:区分”可重试”和”该报错”

  • 529 Overloaded :Anthropic 用来表示服务暂时过载,属于典型的临时性故障,退避重试通常有效。
  • 500 :服务端内部错误,可能是平台 bug,重试意义有限,需要看响应体。
  • 502 / 503 :网关拿不到上游响应或上游不可用,多为瞬时问题。
  • 504 :网关等待上游超时,往往和超长上下文、超大 max_tokens 有关,应同时调大客户端超时时间。

判断原则很简单: 429 和 529、502、503、504 值得退避重试;400、401、403、404 重试一万次结果都一样。

六、一个可以直接用的 Python 重试封装

  1. import os
  2. import time
  3. import random
  4. import logging
  5. import requests
  6. BASE_URL = "https://qianfan.baidubce.com/v2"
  7. API_KEY = os.environ["QIANFAN_API_KEY"]
  8. # 只有这些状态码值得重试
  9. RETRYABLE = {408, 425, 429, 500, 502, 503, 504, 529}
  10. log = logging.getLogger("llm_client")
  11. def _backoff(attempt: int, resp=None) -> float:
  12. """优先遵循服务端 Retry-After,否则指数退避 + 抖动。"""
  13. if resp is not None:
  14. retry_after = resp.headers.get("Retry-After")
  15. if retry_after:
  16. try:
  17. return float(retry_after)
  18. except ValueError:
  19. pass
  20. return min(2 ** attempt, 30) + random.uniform(0, 0.5)
  21. def chat(payload: dict, max_retries: int = 4) -> dict:
  22. headers = {
  23. "Authorization": f"Bearer {API_KEY}", # Bearer 与 Key 之间必须有空格
  24. "Content-Type": "application/json",
  25. }
  26. url = f"{BASE_URL}/chat/completions"
  27. for attempt in range(max_retries + 1):
  28. try:
  29. resp = requests.post(url, json=payload, headers=headers, timeout=(3, 120))
  30. except (requests.ConnectionError, requests.Timeout) as exc:
  31. if attempt == max_retries:
  32. raise
  33. wait = _backoff(attempt)
  34. log.warning("网络异常 %s,%.1fs 后重试 (%d/%d)", exc, wait, attempt + 1, max_retries)
  35. time.sleep(wait)
  36. continue
  37. if resp.status_code == 200:
  38. return resp.json()
  39. # 不可重试的错误:立刻抛出,附带响应体便于定位
  40. if resp.status_code not in RETRYABLE or attempt == max_retries:
  41. raise RuntimeError(f"请求失败 [{resp.status_code}] {resp.text[:500]}")
  42. wait = _backoff(attempt, resp)
  43. log.warning("%d 触发限流/过载,%.1fs 后重试 (%d/%d)",
  44. resp.status_code, wait, attempt + 1, max_retries)
  45. time.sleep(wait)
  46. raise RuntimeError("重试次数已耗尽")

三个细节值得强调: 抖动(jitter)不能省 ,否则多个 worker 会在同一时刻一起重试,把上游二次打挂; 优先读 Retry-After ,服务端比你更清楚该等多久; 超时拆成 (连接, 读取) 元组 ,连接超时给 3 秒,读取超时按输出长度给足。

七、把排查成本降下来的四个习惯

  1. 结构化日志 :每次请求记录 request_id、model、status_code、耗时、token 用量。没有 request_id,找平台技术支持时基本无法定位。
  2. 区分错误类型再告警 :把 401/404 归为”配置错误”,429/529 归为”容量问题”,5xx 归为”上游故障”,三类走不同的处理流程。
  3. 准备降级链路 :主模型返回 529 或持续 5xx 时,自动切到备用模型,而不是把错误抛给用户。这也是大模型 API 服务平台这类统一接入方式的价值所在——切换模型只改一个 model 参数,不用重写鉴权和请求逻辑。
  4. 顺手排除 400 :Invalid parameter、缺少必填参数、敏感内容拦截(如 282004)都会返回 400 系列,这类问题改请求体即可,和鉴权、限流毫无关系。

结语

排查 AI API 错误的核心方法论只有一句: 先定位环节,再选动作。401 查密钥与权限,404 查地址与模型 ID,429 查限流类型与配额,529/5xx 查上游健康度并做退避重试。把这套判断固化成代码里的分支逻辑和日志字段,线上故障的平均恢复时间会明显下降。而在选型阶段就多花十分钟对比模型能力与调用成本,往往比事后排查更省时间。

发表评论

活动