调用大模型 API 返回 401 / 429 / 5xx 分别该怎么排查？

大模型 API 的报错可以先按 HTTP 状态码分三类处理：4xx 里的 401 是「你是谁」的问题，429 是「你发得太多或额度不够」的问题，5xx 是「服务端或上游出了问题」。前两类要改自己的配置或调用方式，后一类以重试和降级为主。

本文的状态码含义以 EasyAPI 文档中的错误码说明为准，排查思路对其他 OpenAI 兼容服务大体也适用。

关键要点

• 错误响应体里有 error 对象，包含 message、type、code 字段，排查时先看 code 和 message。
• 401 对应 invalid_api_key：未提供 Key 或 Key 无效。
• 429 对应 rate_limit_exceeded：请求频率或配额超限。
• 500 对应 server_error：服务端内部错误，应稍后重试。
• 401 和 400 不应该重试，429 和 5xx 才适合做退避重试。

状态码速查表

401：先查密钥和请求头

按下面的顺序检查：

1. 请求头格式。 必须是 Authorization: Bearer sk-...，Bearer 与密钥之间有一个空格。只写密钥不写 Bearer 会被拒绝。
2. Key 是否完整。 确认复制的是 sk- 开头的完整密钥，前后没有空格或换行。
3. 令牌状态。 在控制台的令牌管理里确认该令牌是启用状态、没有过期。
4. Key 与地址是否匹配。 Base URL 指向 https://token.easyapi.com/v1 时，必须使用 EasyAPI 签发的 Key。
5. 环境变量是否生效。 打印变量长度或前几位确认程序真的读到了它（不要打印完整 Key）。

如果返回的是 403，说明密钥有效但没有权限，重点看令牌是否开启了模型限制、IP 白名单是否包含当前出口 IP。

429：区分限流和额度

429 在文档里的含义是「请求频率或配额超限」，两种情况处理方式不同：

• 频率超限：降低并发和每秒请求数，对失败的请求做指数退避重试，批量任务改用队列平滑发送。
• 额度用尽：在令牌管理里查看该令牌的剩余额度，在钱包里查看账户余额；设置过预算的令牌见 怎么给 API Key 设置每日/每月预算上限。
• 上游短时过载：间隔几秒后重试，避免突发大批量请求。

具体的限流阈值文档中没有公开数值，以实际响应和控制台显示为准。

5xx：重试、降级、留证据

5xx 说明问题不在你的请求本身：

1. 间隔几秒后重试，次数设上限。
2. 持续失败时临时切换到备用模型。EasyAPI 的对话接口支持在请求体里用 models 字段给出回退模型序列，主模型没有可用渠道或上游失败且尚未开始输出时会按顺序换用。
3. 长耗时的视频生成应使用异步任务接口并轮询状态，而不是同步等待。
4. 记录请求时间、模型 ID、错误响应，以及响应头里的 X-EasyAPI-Request-Id，联系平台时一并提供（不要附完整 API Key）。

带退避的重试示例

import os, time, random
import openai
from openai import OpenAI

client = OpenAI(
    base_url="https://token.easyapi.com/v1",
    api_key=os.environ["EASYAPI_API_KEY"],
)

def chat_with_retry(messages, max_retries=4):
    for attempt in range(max_retries + 1):
        try:
            return client.chat.completions.create(
                model="deepseek-v4.1-flash-1017",
                messages=messages,
            )
        except openai.AuthenticationError:
            raise                      # 401：重试无意义，直接抛出
        except openai.BadRequestError:
            raise                      # 400：参数问题，先改请求
        except (openai.RateLimitError, openai.InternalServerError,
                openai.APIConnectionError, openai.APITimeoutError):
            if attempt == max_retries:
                raise
            time.sleep(min(2 ** attempt + random.random(), 30))

注意：重试只能缓解瞬时故障。如果 429 是因为额度用尽，重试多少次都不会成功，应先确认原因。

常见问题

返回 401 但我确定 Key 是对的，怎么办？

多数情况是请求头或地址的问题。检查是否漏了 Bearer 前缀、Key 是否属于当前 Base URL 对应的平台、令牌是否过期或被禁用，以及程序是否读到了正确的环境变量。

429 应该等多久再重试？

没有固定数值，建议用指数退避：依次等待约 1、2、4、8 秒并加入随机抖动，同时设置重试上限。如果是额度用尽导致的 429，等待没有用，需要充值或调高额度。

5xx 报错会扣费吗？

是否扣费以控制台调用记录里的实际扣费为准。调用记录可以按时间和模型筛选，日志类型里也有「错误」一类，可以逐条核对。

模型名写错会返回什么？

通常返回参数或模型相关的错误，而不是 401。请核对 model 的拼写和大小写，或调用 GET /v1/models 查看当前 Key 可用的模型。

小结

排查顺序可以记成：401 查密钥和请求头，429 分清限流还是额度，5xx 重试并准备备用模型。完整的错误码说明见 EasyAPI 文档，接入写法可参考 用 OpenAI Python SDK 调用国产大模型要怎么改代码。