OpenAI Responses API 报404怎么排查？接口路径、模型名与平台兼容性

Responses API 是 OpenAI 在 2025 年 3 月推出的新接口，路径为 /v1/responses。很多开发者在接入时遇到 404，但报错信息往往不够明确，排查方向容易跑偏。

这篇文章把 Responses API 404 的常见原因拆开来讲，先定位问题出在哪一层，再决定怎么修。

Responses API 与 Chat Completions 的关系

Responses API 和 Chat Completions 是两个不同的接口：

维度	Chat Completions	Responses API
路径	/v1/chat/completions	/v1/responses
SDK 方法	client.chat.completions.create()	client.responses.create()
推出时间	2023 年	2025 年 3 月
平台支持	几乎所有兼容平台都支持	部分平台尚未支持

如果你在兼容平台上调用 Responses API 返回 404，最常见的原因是平台根本没有实现这个接口。

404 的四种常见原因

原因一：平台不支持 Responses API

这是最常见的 404 原因。很多兼容平台为了兼容更多 SDK，优先支持 Chat Completions，Responses API 的支持进度不一。

判断方法：

# 用 curl 直接请求，看返回什么
curl -X POST "YOUR_BASE_URL/responses" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "YOUR_MODEL", "input": "hello"}'

如果返回 404 且错误信息包含 “not found” 或 “endpoint not found”，大概率是平台不支持。

解决方法：

• 先回退到 Chat Completions 接口
• 向平台确认 Responses API 的支持计划
• 如果平台文档明确写了支持，检查 Base URL 是否正确

原因二：Base URL 路径错误

Responses API 的路径是 {Base URL}/responses。如果 Base URL 写错了，拼接出来的路径就不对。

常见错误：

# 错误：Base URL 带了 /v1，SDK 又拼了 /responses，变成 /v1/responses
# 但如果你的 Base URL 是 https://api.openai.com/v1，这是对的

# 错误：Base URL 带了完整路径
base_url="https://your-platform.com/v1/responses"  # SDK 会拼出 /v1/responses/responses

# 正确：Base URL 只到 /v1
base_url="https://your-platform.com/v1"

原因三：模型 ID 不存在

Responses API 对模型 ID 的要求和 Chat Completions 一样，必须与平台提供的完全一致。模型不存在时，多数平台返回 404 而不是 400。

判断方法：

# 用模型列表接口确认可用模型
models = client.models.list()
for m in models.data:
    print(m.id)

如果列表里没有你要的模型，说明模型 ID 写错了或者平台不支持该模型。

原因四：Codex 等工具的协议升级

OpenAI Codex 在 2026 年 2 月移除了旧的 chat/completions 路径，Responses 现在是唯一合法取值。如果你的网关或兼容平台只支持 /chat/completions，Codex 会报 404。

解决方法：

• 确认网关支持 /responses 端点
• 在配置文件中设置 wire_api = "responses"
• 如果网关不支持，考虑升级或更换

排查流程

遇到 Responses API 404 时，按这个顺序排查：

1. 确认平台是否支持 Responses API
   ↓ 不支持 → 回退到 Chat Completions 或联系平台
   ↓ 支持
2. 检查 Base URL 格式
   ↓ 错误 → 修正 Base URL（只到 /v1，不带尾部斜杠）
   ↓ 正确
3. 确认模型 ID 存在
   ↓ 不存在 → 用 models.list() 确认可用模型
   ↓ 存在
4. 检查网络连通性
   ↓ 不通 → 检查代理、防火墙、DNS
   ↓ 通
5. 用 curl 直接请求测试
   ↓ 成功 → 检查 SDK 配置
   ↓ 失败 → 联系平台确认

快速排错表

现象	最常见原因	排查方法
调用 Responses 返回 404	平台不支持 Responses 接口	用 curl 直接请求确认；回退到 Chat Completions
调用 Chat Completions 正常，Responses 404	平台只实现了 Chat Completions	确认平台文档是否支持 /v1/responses
两个接口都 404	Base URL 路径错误	检查 Base URL 是否只到 /v1
模型相关 404	模型 ID 不存在	用 client.models.list() 确认可用模型
Codex 报 404	网关不支持 Responses 协议	确认网关配置 wire_api = "responses"

和 Chat Completions 404 的区别

维度	Responses API 404	Chat Completions 404
最常见原因	平台不支持该接口	Base URL 或模型 ID 错误
排查重点	先确认平台是否支持	先检查 Base URL 格式
解决方法	回退到 Chat Completions 或升级平台	修正 Base URL 或模型 ID

简单说，Responses API 的 404 大部分是平台兼容性问题，不是你的配置错了。先确认平台是否支持，再检查 Base URL 和模型 ID，基本能解决大部分问题。