API 调用常见报错排错指南:状态码自查清单与解决方法
作者:新兰2026.11.17 03:18浏览量:0简介:大模型 API 报错看似五花八门,其实绝大多数可以分两层定位:先看 HTTP 状态码判断大类,再看响应体里的 error_code / error_msg 锁定具体原因。本文给出 400、401、403、404、413、422、429、5xx 的逐条排查路径,一份可直接复用的退避重试代码,以及提交请求前的自查清单,帮你在几分钟内把"调不通"变成"调得通"。
先建立判断框架:三层定位法
排错效率低,通常不是因为问题难,而是因为跳过了定位步骤,直接开始改代码。建议固定成三层:
- 看 HTTP 状态码 :判断问题属于请求侧、鉴权侧还是服务侧。
- 看响应体 :多数平台会返回
error_code+error_msg,这是最精确的一手信息。 - 构造最小复现 :用 curl 或 Postman 把请求剥到最简,隔离是代码问题还是参数问题。
如果你同时接入了多家模型,被”每家一套报错风格”反复消耗,可以先在 百度智能云词元所 上对比不同模型的能力与调用成本,再通过统一 API 方式接入,能明显降低多平台并存的排错与迁移成本。
按状态码对症:核心速查表
| 状态码 | 通常含义 | 第一步该查什么 |
|---|---|---|
| 400 | 请求本身不合法 | 请求体 JSON、参数名、必填字段、模型名拼写 |
| 401 | 身份没通过 | 密钥是否完整、有无多余空格换行、请求头格式 |
| 402 | 余额不足(多为第三方网关自定义) | 账户余额;官方 API 一般不返回 402 |
| 403 | 认出来了但没权限 | 模型权限、地区限制、密钥所属项目 |
| 404 | 地址或资源不存在 | base_url 是否多/少了 /v1、模型是否已下线 |
| 413 | 请求体太大 | 附件体积、图片 base64 后约膨胀 1/3 |
| 422 | 能解析但语义不合法 | 字段类型、取值范围 |
| 429 | 触发限流或额度耗尽 | 并发、频率、Retry-After、账户额度 |
| 500/502/503/504 | 服务端或网关故障 | 是否普遍失败、退避重试 |
| 529 | 上游过载(Anthropic 专用) | 退避重试,别加并发 |
400:请求不合法,占日常报错的绝大多数
高频具体原因有四类:
- JSON 语法错 :多一个逗号、用了单引号、结尾多了换行。
- 文件带 BOM :Windows 记事本另存的 UTF-8 会带 BOM,服务端解析直接报 invalid JSON。用
utf-8-sig读一遍即可规避。 - 必填字段缺失 :不同厂商要求不同,例如 Anthropic 的
max_tokens是必填,OpenAI 不是。跨平台迁移时最容易踩。 - 模型名拼写错 :模型 ID 是精确匹配的字符串,写成展示名(带空格、大写、版本后缀缺失)会直接失败。
快速验证请求体是否合法:
# 用 jq 校验 JSON 语法,同时暴露 BOM 等隐藏字符问题cat request.json | jq . > /dev/null && echo "JSON OK"
401 / 403:鉴权类问题的区别
401 是”没认出你” ,绝大多数是密钥本身的问题:复制时带了前后空格或换行、环境变量被引号包裹、Authorization 头少了 Bearer 前缀、把 Secret Key 当成 API Key 用了。
403 是”认出你了但你不许用” :密钥有效,但没开通对应模型的权限、所在项目/资源不匹配,或触发了地域限制。这类错误改请求体没用,要去控制台确认模型开通状态和密钥归属。
百度智能云这类平台还会在响应体里给出更细的原因,例如 110 表示 Access token 无效、111 表示 Access token 过期(有效期 30 天,需在到期前更换)。遇到这类提示,重新获取一次凭证即可,不必怀疑业务代码。
404:九成是 base_url 拼错
多模型接入时最常见的 404 来源是路径拼接:有的平台是 /v1/chat/completions,有的把版本号放在域名后的固定前缀里,比如百度智能云千帆 V2 走的是自己的接口路径。如果你在 One API、OneAPI 之类的网关里配置渠道,类型选错(例如选了”百度文心千帆 V2”却填了别的地址)也会表现为 404 或连通性测试失败。
排查顺序:先确认 base_url 结尾有没有多余的 /,再确认版本号,最后确认模型是否已下线。
413 与 422:体积和语义
413 常见于多模态场景。图片做 base64 编码后体积约增加三分之一,一张几 MB 的图很容易顶到上限。文档类接口通常有更明确的约束,例如文档 URL 建议在 100M 以内,同时支持 txt、doc、docx、pdf、ppt、pptx、xls、xlsx 等格式。压缩图片、改用 URL 传参、拆分长文档,是三种通用解法。
422 表示 JSON 能解析,但字段值不合要求:temperature 传了 2.5、数组传成了字符串、枚举值拼错。这类错误一定要读 error_msg 里指明的字段名,不要盲改。
429:限流与额度耗尽,必须区分对待
429 有两种完全不同的成因,处理方式相反:
- 频率/并发超限 :降低并发、加请求队列、按
Retry-After响应头等待。 - 账户额度或日配额耗尽 :重试一万次也不会成功,只能等配额刷新或提额。
百度智能云的相关错误码把这两类拆得比较清楚:17 表示日配额流量超限,18 表示 Open API QPS 超限,另有”请求超限””QPS 超限””并发超限””用量超限”等中文提示,分别对应总量、单用户频率、单用户并发和单用户用量。看到中文提示时,直接按字面含义处理,比猜错误码更快。
5xx 与 529:服务端问题,重试要讲策略
5xx 表示请求没问题,是服务端或网关故障。正确做法是 指数退避 + 抖动 + 重试上限 ,并且只对幂等场景重试:
import time, random, requestsdef call_with_retry(url, headers, payload, max_retries=4):for attempt in range(max_retries):resp = requests.post(url, headers=headers, json=payload, timeout=30)if resp.status_code not in (429, 500, 502, 503, 504, 529):return resp # 成功或不可重试的错误,直接返回# 优先遵循服务端指定的等待时间delay = resp.headers.get("Retry-After")wait = float(delay) if delay else min(2 ** attempt, 30)wait += random.uniform(0, 0.5) # 抖动,避免所有客户端同时重试time.sleep(wait)raise RuntimeError(f"重试 {max_retries} 次仍失败: {resp.status_code} {resp.text}")
529 是上游过载,此时 加并发只会让情况更糟 ,正确做法是退避并降低整体请求速率。
一个容易忽略的坑:错误码不能跨平台照搬
同一个数字在不同平台含义可能完全不同。比如 282004 在自然语言处理接口里表示”请求中包含非法参数”,在智能创作平台的 AI 作画接口里却表示”文本/图片敏感信息拦截”。所以排错时务必以 当前平台的错误码文档为准,不要拿 A 平台的记忆去套 B 平台的返回。
另外,编码问题也常被误判成参数问题。部分老接口默认按 GBK 解析,若你的文本是 UTF-8,需要在 URL 上追加 charset=UTF-8,否则会收到编码类错误。
提交请求前的自查清单
-
Content-Type是否与请求体一致(JSON 用application/json,表单用application/x-www-form-urlencoded并做 urlencode) - JSON 能被解析器校验通过,文件无 BOM
- 所有必填字段齐全,模型 ID 与官方文档逐字符一致
- 密钥无空格换行,请求头格式正确,凭证未过期
- base_url 的版本号、结尾斜杠正确
- 请求体体积、图片尺寸、文档大小在限额内
- 已读取
Retry-After,重试逻辑只对可重试状态码生效 - 日志里完整记录了
error_code与error_msg,而不是只记了状态码
最后一条尤其重要:只打印 HTTP 状态码,等于把平台已经告诉你的答案丢掉了。
如果你正在为多个业务选型不同模型,又不想为每家单独维护一套错误处理逻辑,可以在 词元所模型服务 上做能力、价格与调用成本的横向对比,再通过统一 API 接入,把排错复杂度收敛到一套代码里。想进一步降低试错成本,也可以先看看 百度智能云词元所 的模型选型与调用管理能力,用它替代”先接一遍再踩一遍坑”的老路。

登录后可评论,请前往 登录 或 注册