OpenAI兼容API报401/404/429怎么解决？API Key、Base URL、模型名排查

使用 Python 调用 OpenAI API 或 OpenAI 兼容接口时，比较常见的三个错误是：

text 复制代码

401 Unauthorized
404 Not Found
429 Too Many Requests

虽然都是"API 调用失败"，但排查方向并不一样。

报错	优先检查
401	API Key、认证
404	Base URL、Model ID、接口路径
429	请求频率、Token、限流

OpenAI Python SDK 当前分别将 401、404 和 429 映射为 AuthenticationError、NotFoundError 和 RateLimitError。

如果代码一直跑不通，建议先不要在 LangChain、Agent 或完整业务项目里反复修改，而是先用最小请求确认 API 本身是否正常。

一、先用最小代码测试API

先安装或升级 OpenAI Python SDK：

bash 复制代码

pip install -U openai

当前最新版 OpenAI Python SDK 要求 Python 3.10 或更高版本。

可以先检查本地版本：

bash 复制代码

python --version

对于 OpenAI 兼容接口，第一次排错时可以先使用 Chat Completions 做最小验证，因为不少兼容服务仍然以 /v1/chat/completions 为主要接口。

python 复制代码

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="YOUR_BASE_URL"
)

response = client.chat.completions.create(
    model="YOUR_MODEL",
    messages=[
        {
            "role": "user",
            "content": "你好，请回复测试成功"
        }
    ]
)

print(response.choices[0].message.content)

只需要替换三个参数：

参数	填写内容
`YOUR_API_KEY`	实际API Key
`YOUR_BASE_URL`	API服务提供的Base URL
`YOUR_MODEL`	实际Model ID

如果是直接调用 OpenAI 官方 API，则可以按照官方文档使用默认地址；如果使用兼容接口，Base URL、Model ID 和支持的 API 类型应以对应服务文档为准。

OpenAI 官方当前推荐新项目优先使用 Responses API，但 Chat Completions 仍然继续支持。

二、401 Unauthorized：先检查API Key

如果出现：

text 复制代码

401 Unauthorized

或者：

text 复制代码

AuthenticationError

首先应该检查认证信息。

常见原因包括：

检查项	常见问题
API Key	复制错误、少字符、多空格
Key状态	已删除、失效
环境变量	程序实际读取的是旧Key
Base URL	Key与当前API服务不匹配
权限	当前凭证没有对应资源权限

OpenAI Python SDK 当前把 HTTP 401 映射为 AuthenticationError，403 则映射为 PermissionDeniedError。

所以可以简单理解为：

401优先查认证，403再重点检查权限。

检查环境变量

如果代码通过环境变量读取 Key，可以先确认当前程序到底读取了什么：

python 复制代码

import os

key = os.getenv("OPENAI_API_KEY")

if key:
    print(key[:8])

这里只查看前几位即可，不要把完整 API Key 输出到日志、截图或者公开代码中。

如果发现程序仍然读取旧 Key，就需要检查系统环境变量、.env 文件或者 IDE 的运行配置。

三、404 Not Found：先检查Base URL

如果出现：

text 复制代码

404 Not Found

或者：

text 复制代码

NotFoundError

首先检查 Base URL。

假设 API 文档给出的 Base URL 是：

text 复制代码

https://example.com/v1

那么客户端可以配置为：

python 复制代码

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://example.com/v1"
)

不要在没有查看文档的情况下自己改成：

text 复制代码

https://example.com

也不要直接把完整接口路径填进 base_url：

text 复制代码

https://example.com/v1/chat/completions

因为 SDK 会根据调用的方法继续拼接具体接口路径。

还要检查 /v1 有没有重复。

例如：

text 复制代码

https://example.com/v1/v1

这种配置就可能直接导致404。

可以打印当前客户端使用的地址：

python 复制代码

print(client.base_url)

先确认程序实际请求的基础地址是不是你预期的地址。

四、404也可能是API类型不匹配

这是现在排查404时比较容易漏掉的一点。

OpenAI 当前同时支持：

API	常见Endpoint	Python调用
Responses API	`/v1/responses`	`client.responses.create()`
Chat Completions	`/v1/chat/completions`	`client.chat.completions.create()`

OpenAI 官方目前推荐新项目使用 Responses API，同时继续支持 Chat Completions。

Responses API示例

python 复制代码

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="YOUR_BASE_URL"
)

response = client.responses.create(
    model="YOUR_MODEL",
    input="你好，请回复测试成功"
)

print(response.output_text)

Chat Completions示例

python 复制代码

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="YOUR_BASE_URL"
)

response = client.chat.completions.create(
    model="YOUR_MODEL",
    messages=[
        {
            "role": "user",
            "content": "你好"
        }
    ]
)

print(response.choices[0].message.content)

如果模型或者 API 服务只支持其中一种接口，而代码调用了另一种，就可能出现404、接口不存在或者模型不支持当前 Endpoint 等错误。

因此404不能只看 Base URL，还要同时确认：

检查项	要确认什么
Base URL	地址是否正确
Model ID	模型名称是否正确
Endpoint	当前路径是否存在
API类型	Responses还是Chat Completions
权限	当前Key是否能够调用该模型

五、Model ID写错也可能导致请求失败

模型的产品名称和真正用于 API 请求的 Model ID 不一定完全相同。

例如实际 Model ID 是：

text 复制代码

model-a

但代码写成：

python 复制代码

model="model_a"

对于 API 来说就是两个不同的值。

如果当前服务实现了模型列表接口，可以尝试：

python 复制代码

models = client.models.list()

for model in models.data:
    print(model.id)

如果没有实现 /models，就直接从对应 API 文档或控制台复制 Model ID。

不要根据产品名称自己猜。

需要注意，不同 OpenAI 兼容服务对错误码的实现可能存在差异。

模型不存在可能表现为404，也可能是400或者其他业务错误，因此最终仍然要结合完整错误正文判断。

六、429 Too Many Requests：重点检查限流

如果出现：

text 复制代码

429 Too Many Requests

或者：

text 复制代码

RateLimitError

OpenAI 官方 API 场景下，首先应该检查 Rate Limit，也就是单位时间内允许的请求数和 Token 数。OpenAI 官方说明，429 Rate Limit 常见于请求或 Token 达到当前速率限制。

常见指标包括：

指标	含义
RPM	Requests Per Minute，每分钟请求数
TPM	Tokens Per Minute，每分钟Token数
并发	同一时间发出的请求数量
Token规模	单次请求的输入和输出长度

例如限制为 60 RPM，并不意味着一定可以在一秒内一次性发送60个请求。

OpenAI 官方说明，速率限制可能应用到比一分钟更短的时间窗口，因此短时间突发大量请求同样可能触发429。

七、429不要无限重试

下面这种写法不推荐：

python 复制代码

while True:
    try:
        request()
    except:
        continue

如果已经触发限流，立即不停发送相同请求通常只会产生更多失败。

OpenAI 官方建议针对 Rate Limit 使用指数退避，也就是每次失败后等待一段时间，再逐步增加等待时间。失败请求本身也可能计入速率限制，因此连续无间隔重试无法有效解决问题。

八、Python SDK本身已经带自动重试

这里还有一个很容易忽略的问题。

OpenAI Python SDK 当前默认会对部分临时错误自动重试 2次，包括：

错误	默认自动重试
网络连接错误	是
408 Request Timeout	是
409 Conflict	是
429 Rate Limit	是
5xx服务端错误	是

SDK 使用短时间指数退避，并允许通过 max_retries 调整。

例如：

python 复制代码

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="YOUR_BASE_URL",
    max_retries=5
)

如果自己的业务代码已经实现了一套重试机制，也可以关闭 SDK 默认重试：

python 复制代码

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="YOUR_BASE_URL",
    max_retries=0
)

这样可以避免：

text 复制代码

SDK自动重试
+
业务代码再次重试

最终导致一次失败请求实际发送很多次。

九、兼容接口出现429时要看完整错误正文

对于 OpenAI 官方 API，429首先应该按照 Rate Limit 排查。

如果使用的是其他 OpenAI 兼容服务，则不同服务对限流、账户额度和业务错误的定义可能不完全相同。

因此不要只看：

text 复制代码

还要继续看返回的具体错误内容。

可以按照下面的思路判断：

错误正文	优先排查
`rate limit`	RPM、TPM
`too many requests`	请求频率、突发并发
明确的额度提示	当前服务的账户或额度设置
其他业务错误	对照对应API文档

这样比单纯根据状态码猜问题更可靠。

十、排错时把完整异常打印出来

很多测试代码最后只写：

python 复制代码

print("调用失败")

这种信息几乎没有排错价值。

OpenAI Python SDK 对网络连接问题会抛出 APIConnectionError；对 4xx、5xx 等非成功 HTTP 状态则会抛出 APIStatusError 的子类。

可以这样写：

python 复制代码

import openai
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="YOUR_BASE_URL"
)

try:
    response = client.chat.completions.create(
        model="YOUR_MODEL",
        messages=[
            {
                "role": "user",
                "content": "你好"
            }
        ]
    )

    print(response.choices[0].message.content)

except openai.APIConnectionError as e:
    print("连接失败：", e)

except openai.APIStatusError as e:
    print("状态码：", e.status_code)
    print("错误类型：", type(e).__name__)
    print("错误信息：", e)
    print("Request ID：", e.request_id)

其中失败请求的 request_id 可以通过 APIStatusError 获取，排查官方 API 问题或者提交日志时很有用。

常见异常和排查方向如下：

SDK异常	优先排查
`AuthenticationError`	API Key、认证
`PermissionDeniedError`	权限
`NotFoundError`	Base URL、Model ID、Endpoint
`RateLimitError`	RPM、TPM、请求频率
`APIConnectionError`	网络、DNS、连接

OpenAI SDK 当前对应关系中，401、403、404、429分别对应上述专用异常类型。

十一、401、404、429快速排错表

最后可以直接保存这张表：

报错	第一检查项	常见原因
401	API Key、认证	Key错误、失效、认证配置错误
404	Base URL、Model ID、Endpoint	地址错误、模型不存在、API类型不匹配
429	RPM、TPM、请求频率	调用过快、Token速率超限

如果只想记一句：

401查认证，404查URL、模型和接口，429查限流。

总结

遇到 OpenAI API 或兼容接口报错时，最容易浪费时间的做法，就是一开始就在完整项目里到处修改代码。

更有效的方式是先确认：

text 复制代码

API Key
Base URL
Model ID
API类型

然后使用最小请求测试。

401优先检查 API Key 和认证；404重点检查 Base URL、Model ID，以及 Responses / Chat Completions 是否匹配；429则重点检查 RPM、TPM、请求频率和重试策略。

OpenAI 当前推荐新项目使用 Responses API，但 Chat Completions 仍然继续支持。对于 OpenAI 兼容服务，则需要进一步确认对应服务到底实现了哪些 Endpoint。

先把最基础的 API 调用跑通，再接回 LangChain、Agent 或完整业务代码，通常会更容易定位问题。