OpenAI API 404 endpoint not found 怎么解决？

更新于 2026-11-08 · runapi.cfd

简答：如果 OpenAI API 返回 404 endpoint not found，先保存最终请求 URL、方法、状态码和 error.message，再判断是路径 404、模型 404 还是 Azure deployment 404。最小修复顺序是：核对 Base URL 是否重复或缺少 /v1，确认 Responses 与 Chat Completions 路径匹配，用同一 Key 请求模型列表，最后再检查模型、项目和权限。

定义：OpenAI API 的 404 表示请求指向的资源、模型或路由当前不可用，不等于所有 404 都是模型 ID 错误。

先试这一步：30 秒判断 404 到底是哪一类

截至 2026-11-08 核验，官方错误文档将资源不存在归为 NotFoundError；错误对象中的 error.code、error.message 和 error.param 是定位入口。先不要直接换模型或反复重试，按下面顺序保存信息。

看到的现象	优先怀疑	先做什么
访问接口就返回 404，响应体像网关错误	Base URL、/v1 或 Endpoint 拼接错误	打印最终请求 URL 和方法，检查是否重复出现 `/v1` 或把完整 Endpoint 填进了 Base URL
HTTP 404，响应体明确写 model not found	模型 ID、项目或模型可用范围	使用同一 API Key 请求 `/v1/models`，从返回的 `id` 中复制模型标识
Azure OpenAI 返回 404	资源 endpoint、deployment name 或 API version	核对 Azure 资源地址、部署名和当前 REST 文档要求
第三方兼容网关的模型列表能打开，但生成请求 404	网关只实现部分路由，或模型目录与生成路由不同步	分别测试模型列表和目标生成 Endpoint，并查看网关返回的 request-id 或日志

最小成功判定：最终 URL 和 HTTP 方法正确；响应状态为成功；响应体是 JSON 且包含可识别文本。流式请求还要确认响应类型和事件持续返回，但普通文本请求成功不能证明流式、工具调用或视觉接口也兼容。

先区分 Base URL、完整 Endpoint 与 /v1

OpenAI 官方文档把模型列表路径写作 /models，其示例完整地址是 https://api.openai.com/v1/models；Chat Completions 的路径是 /chat/completions，Responses 的路径是 /responses。因此，使用 SDK 或客户端时，Base URL 如何拼接必须以该工具的配置说明为准，不能把完整请求地址机械地填入 Base URL。

常见错误拼接包括：

https://api.openai.com/v1/v1/models：Base URL 和客户端都自动添加了 /v1。
https://api.openai.com/v1/chat/completions/chat/completions：把完整 Endpoint 当成 Base URL，客户端再次拼接路径。
https://api.openai.com/chat/completions：缺少当前接口所需的版本路径。
把 /responses 的请求体发送到 /chat/completions，或反过来：路径和 JSON 字段不匹配。

排查时把配置拆成三项记录：Base URL、客户端自动追加的路径、最终请求 URL。如果 SDK 没有直接暴露最终 URL，可在 HTTP 客户端层启用不含密钥的请求日志，或使用代理调试工具只记录域名、路径、方法、状态码和响应头。

用同一个 API Key 做最小请求验证

下面的 curl 仅使用占位变量，不代表任何第三方服务的固定域名或模型名。先替换 $OPENAI_API_KEY；如果使用兼容网关，同时替换 $BASE_URL，并以该网关当前文档确认是否需要 /v1。

第一步：请求模型列表。

curl "$BASE_URL/models" -H "Authorization: Bearer $OPENAI_API_KEY"

预期成功信号：HTTP 状态正常，JSON 中出现 data 数组，并能找到模型对象的 id。失败分支：如果这里已经 404，优先修 Base URL、版本路径或网关路由；如果是 401，先修 Key；如果是 403，检查组织、项目或访问权限。

第二步：用同一个模型 ID 测试 Chat Completions。将 MODEL_ID 替换为模型列表返回的完整 id，不要使用网页展示名或自行猜测的旧名称。

curl "$BASE_URL/chat/completions" -H "Authorization: Bearer $OPENAI_API_KEY" -H "Content-Type: application/json" -d '{"model":"MODEL_ID","messages":[{"role":"user","content":"Reply with OK"}]}'

预期成功信号：返回 JSON，且包含可识别的回复文本，例如 choices 中的 message 内容。失败分支：若请求路径 404，回到 Endpoint 拼接；若消息明确是 model not found，回到模型 ID、项目和模型目录；若状态码正常但响应体不是预期 JSON，检查是否经过了代理层或网关转换。

Responses API 使用不同路径和请求体。官方参考文档示例为 POST /v1/responses，不要把它与 Chat Completions 的 messages 请求体混用。

Python 和 Node.js 中如何避免把路径拼错

Python 最小验证：先替换 BASE_URL、API_KEY 和 MODEL_ID。具体 SDK 版本对 Base URL 的拼接方式可能不同，运行前应查看当前 SDK 文档，并在 HTTP 层确认最终 URL。

from openai import OpenAI client = OpenAI(api_key="API_KEY", base_url="BASE_URL") response = client.chat.completions.create(model="MODEL_ID", messages=[{"role":"user", "content":"Reply with OK"}]) print(response.choices[0].message.content)

预期成功信号：程序输出模型文本。失败分支：捕获异常并记录 status_code、request_id、错误类型和 message；不要输出完整 API Key。若 SDK 报 404，先确认 base_url 是客户端要求的基础地址，而不是已经带有 /chat/completions 的完整地址。

Node.js 最小验证：替换环境变量后运行；若客户端自动拼接版本路径，不要在 Base URL 中重复添加同一段路径。

import OpenAI from "openai"; const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY, baseURL: process.env.BASE_URL }); const r = await client.chat.completions.create({ model: process.env.MODEL_ID, messages: [{ role: "user", content: "Reply with OK" }] }); console.log(r.choices[0].message.content);

预期成功信号：控制台出现回复文本。失败分支：在异常处理中查看 HTTP 状态、错误对象和 request-id；如果只看到一张 HTML 404 页面，通常应优先检查域名、反向代理路由或 Base URL，而不是先修改模型参数。

官方 OpenAI、Azure OpenAI 与兼容接口对照

接口类型	路径或字段重点	404 核查顺序
官方 OpenAI	确认 `/v1`、`/models`、`/chat/completions` 或 `/responses` 与请求体一致	最终 URL → 方法 → 模型 ID → API Key 对应的组织或项目 → 响应体
Azure OpenAI	核对资源 endpoint、deployment name；部分新接口路径和 API version 规则不同	资源地址 → deployment name → API version → 认证方式 → 响应体
第三方兼容网关	以当前实例配置确认 Base URL、认证头、可用模型和支持的 Endpoint	网关域名 → 路由路径 → 认证头 → 模型目录 → 网关日志和 request-id

Azure 官方排错文档将 404 的常见原因列为 endpoint URL 错误、deployment name 不存在或 API version 不支持；微软当前端点说明还指出，使用 Azure 的 OpenAI v1 API 时，可能使用 /openai/v1/ 路由，并把 deployment name 放入 model 字段。实际字段和版本仍应以当前资源文档为准。

兼容接口尤其要避免一个误区：/models 能返回列表，不代表所有模型都支持同一生成路径，也不代表 Responses、Chat Completions、流式或工具调用全部实现。应以实例文档、模型目录和一次最小文本请求分别核实。

按最终 URL、状态码和响应体固定排错

记录请求元数据：时间、时区、最终 URL、HTTP 方法、状态码、响应 Content-Type、错误 code、message、param 和 request-id。
确认请求没有被改写：检查反向代理、SDK、环境变量和客户端设置是否重复添加路径，尤其是 /v1。
确认接口与请求体对应：Chat Completions 使用 messages；Responses 使用其对应的 input 等字段，不要跨接口复制请求体。
确认模型来源：优先从同一身份请求的模型列表复制完整 model id；模型列表不可用时，不要把猜测的模型名当作已核实配置。
确认权限上下文：检查 API Key 所属组织、项目、资源和部署；404 与 403 的判断以响应体为准，不要仅凭页面提示猜测。
检查代理层：如果响应是 HTML、网关默认 JSON 或没有 API 错误结构，可能是域名、反向代理或路由层返回的 404。
最后看限速和服务状态：429、500、503 不是路径 404，分别按限速、服务端错误或临时过载处理。对这些状态码盲目重试不能修复路径问题。

提交日志给服务方前，至少遮盖 API Key、Authorization 头、完整请求内容中的隐私数据，并保留状态码、错误对象、时间、请求方法、路径和 request-id。

常见问题

OpenAI API 返回 404 endpoint not found，是不是模型不存在？

不一定。若错误信息指向 model not found，才优先查模型 ID、项目和模型可用范围；如果响应像网关页面或请求路径本身 404，应先检查 Base URL、/v1 和 Endpoint 拼接。

Base URL 应该填写到哪里？

不能一概而论。先看客户端是否自动追加 /v1、/chat/completions 或 /responses，再记录最终 URL。不要把完整 Endpoint 填进会自动拼接路径的 Base URL，否则可能出现重复路径。

为什么 /v1/models 能访问，/v1/chat/completions 仍然 404？

模型列表路由与生成路由可能由不同网关规则处理。应确认目标服务确实实现 Chat Completions，核对认证头、模型字段和请求体，并查看响应中的 request-id 或服务端日志。

Azure OpenAI 的 404 和官方 OpenAI 的 404 有什么不同？

Azure 404 常见核查项包括资源 endpoint、deployment name 和 API version；官方 OpenAI 则重点核对 /v1、Endpoint、模型 ID 及项目上下文。两者不能直接套用同一 URL 格式。

如何在排错时避免泄露 API Key？

只记录域名、路径、方法、状态码、Content-Type、错误 code、message、时间和 request-id；Authorization 头、完整 Key、隐私输入和敏感响应内容应遮盖或删除。

Run API