OpenAI API 401 怎么解决？先看 error.code，再用 curl 3 步定位
简答：OpenAI API 返回 401 时，优先检查 API Key、Authorization: Bearer 请求头和实际请求端点，不要先反复更换模型。先在发起请求的同一环境执行 <code>curl -i https://api.openai.com/v1/models -H "Authorization: Bearer $OPENAI_API_KEY"</code>，再根据返回的 <code>error.code</code> 分流。官方 OpenAI API 与兼容网关必须分别核对 Base URL、Key、路径和认证规则。
定义：401 Unauthorized 是 HTTP 认证失败响应；在 OpenAI API 中，常见原因包括 Key 错误或撤销、组织或项目不匹配、账号缺少组织成员关系，以及请求来源 IP 不在允许列表中。
先执行这 3 步：不要从客户端界面猜配置
- 读取完整错误字段：保留 HTTP 状态码、
error.message、error.type、error.code，以及响应中返回的请求 ID；不要记录完整 API Key 或 Authorization 请求头。 - 在实际运行环境执行最小请求：本文只使用 curl，避免 SDK、客户端和业务参数干扰认证判断。
curl -i https://api.openai.com/v1/models -H "Authorization: Bearer $OPENAI_API_KEY" - 按端点分流：如果请求发往
api.openai.com，按 OpenAI 官方错误代码处理；如果请求发往兼容网关或其他 API Router，则必须改查该服务当前公开文档，不能直接套用官方 Key、模型或组织参数。
OpenAI 官方错误代码文档将 401 分为无效认证、错误 API Key、组织成员资格和 IP 未授权等情况。参考：OpenAI API Error codes。
| 响应或错误特征 | 优先检查 | 处理方向 |
|---|---|---|
| 401，提示 Invalid Authentication | Key、组织 ID、项目 ID、权限 | 确认请求使用的是当前组织或项目对应的凭证 |
| 401，提示 Incorrect API key provided | 拼写、空格、换行、旧值、Key 是否被删除 | 重新读取环境变量，必要时轮换 Key 并同步部署配置 |
| 401，提示必须属于组织 | 账号是否仍属于目标组织或项目 | 由组织或项目管理员处理成员关系 |
401，代码为 ip_not_authorized | 服务器真实公网出口 IP | 核对组织或项目的 IP 允许列表，配置变更后等待生效 |
| 403、404、429 或 500 | 不要继续按 401 处理 | 分别转查地区或权限、路径或资源、限速或额度、服务端状态 |
按错误码修复 API Key、请求头和项目配置
1. 先确认程序读取到的是当前 Key
官方文档列出的错误 API Key 原因包括拼写错误、额外空格、Key 属于其他组织或项目、Key 已删除或停用，以及本地仍缓存旧 Key。先检查变量是否存在，不要把完整值打印到终端、日志、截图或工单。
# macOS / Linux
if [ -n "$OPENAI_API_KEY" ]; then echo "OPENAI_API_KEY is set"; else echo "OPENAI_API_KEY is missing"; fi
# PowerShell
if ($env:OPENAI_API_KEY) { "OPENAI_API_KEY is set" } else { "OPENAI_API_KEY is missing" }
本地终端显示变量存在，不代表容器、CI、云函数或进程管理器也读取到了同一个值。应在实际发起请求的进程或部署环境中检查 Secret 是否注入，应用重启后是否加载新值。OpenAI 建议将 Key 放在环境变量或密钥管理服务中，不要提交到代码仓库或放进浏览器、移动应用等客户端环境。参考：OpenAI API Key 安全最佳实践。
2. 核对 Authorization: Bearer 格式
官方 API 使用 HTTP Bearer 认证，格式应为 Authorization: Bearer OPENAI_API_KEY。Bearer 与 Key 之间需要空格，不能重复拼接 Bearer，也不应把 Key 放到 URL 查询参数中。参考：OpenAI API Reference：Authentication。
如果最小 curl 请求成功，但 Node.js、Python 或桌面客户端仍然 401，优先检查客户端实际读取的变量、Base URL、路径和代理。反向代理、网关或自定义 HTTP 中间件也可能删除或改写 Authorization。日志只显示变量是否存在或经过脱敏的部分字符，不能打印完整密钥。
3. 核对组织和项目
如果账号属于多个组织，或使用项目相关 Key，官方 API Reference 支持通过 OpenAI-Organization 和 OpenAI-Project 请求头指定目标组织与项目。组织 ID 和项目 ID 应从当前控制台设置中复制，不要凭名称猜测。
curl -i https://api.openai.com/v1/models -H "Authorization: Bearer $OPENAI_API_KEY" -H "OpenAI-Organization: $ORGANIZATION_ID" -H "OpenAI-Project: $PROJECT_ID"
如果错误明确提示账号不是组织成员，重新生成 Key 通常不是第一步；应确认账号是否仍在目标组织或项目中，并由管理员处理邀请、成员关系或项目设置。官方错误代码文档明确将组织成员资格列为 401 的一种情况，但并非所有 401 都来自组织问题。
出现 ip_not_authorized：检查真实出口 IP
当错误代码为 ip_not_authorized 时，官方说明是请求 IP 与组织或项目配置的 IP 允许列表不匹配。这里要查的是发起 API 请求的公网出口 IP，不是电脑的内网地址、容器地址或服务器网卡地址。
- 从实际运行请求的服务器、容器或云函数环境确认公网出口 IP。
- 检查 NAT 网关、代理、防火墙或云平台是否改变了出口地址。
- 确认当前 IP 允许列表作用于 API Key 对应的组织或项目。
- 修改配置后等待最多 15 分钟，再从同一运行环境重新执行最小 curl。
OpenAI 官方 IP 允许列表文档给出了上述验证方向，并说明未加入允许列表的请求会返回 401 和 ip_not_authorized。参考：OpenAI API IP allowlist。
如果本地请求成功、部署服务器失败，优先检查部署环境的出口 IP 和 Secret 注入情况，而不是直接判断模型或账号不可用。
官方 OpenAI API 与兼容网关要分开排查
相同的 OpenAI 兼容格式，不代表不同服务共享认证规则。使用官方 API 时，本文示例中的主机和路径是 https://api.openai.com/v1/models；使用其他兼容网关、代理或 API Router 时，Base URL、是否包含 /v1、模型 ID、Key 创建方式和请求头都必须以该服务当前公开文档为准。未核实的域名、模型名和路径不要写入生产配置。
| 现象 | 更可能的排查范围 | 下一步 |
|---|---|---|
官方 /v1/models 返回成功，客户端返回 401 | 客户端变量、Base URL、路径或代理 | 核对客户端最终请求的主机、路径和认证头 |
| 官方端点返回 401 | 官方 Key、组织、项目或 IP 允许列表 | 读取 error.code，按官方文档处理 |
| 兼容网关返回 401，官方端点未测试 | 兼容网关的 Key、端点或认证规则 | 只按该服务当前文档核对，不套用官方组织头 |
| curl 成功，SDK 失败 | SDK 版本、环境变量、代理和自定义请求头 | 在同一进程检查配置是否存在，并比较最终 URL |
这一步的核心不是判断哪个服务“更好”，而是先确认 401 发生在哪个主机、哪个路径和哪一套凭证上。边界没有分清时，反复换模型或重装客户端通常不能解决认证根因。
Key 泄露或平台侧异常时怎么处理
如果 Key 出现在公开仓库、前端代码、日志、截图或工单中，应先轮换并撤销旧 Key，再更新所有应用、容器和自动化任务中的配置。OpenAI 的安全建议包括使用独立 Key、设置轮换流程、监控用量，以及避免在客户端环境暴露 Key。参考：API Key 安全最佳实践。
如果 Key、请求头、组织项目和 IP 允许列表都已核对，且 401 只是在短时间内间歇出现，可以查看官方状态页。OpenAI 曾在 2026 年 4 月 12 日至 2026 年 4 月 14 日记录 API 端间歇性 401，受影响组件包括 Chat Completions、Responses 和 Embeddings，状态页随后标记为已恢复。此类历史事件不能证明当前一定是平台故障，但说明间歇性 401 时应同时检查状态页，而不是连续轮换 Key。参考：OpenAI Status：Elevated 401 errors for API endpoints。
- 记录发生时间、时区、请求主机、路径、HTTP 状态和脱敏后的错误字段。
- 记录模型与客户端版本，但不要提交完整 Key、Cookie 或 Authorization 头。
- 如果问题只发生在一个部署环境，优先复核 Secret、出口 IP 和代理。
- 如果多个环境同时出现间歇性 401，再查看官方状态页和支持渠道。
常见问题
401 Unauthorized 就一定是 API Key 无效吗？
不一定。官方错误代码文档还列出了组织成员资格和 IP 未授权等 401 情况。应继续读取 error.message、error.type 和 error.code，再决定是检查 Key、组织项目还是出口 IP。
Key 没有过期，为什么仍然返回 401？
Key 未过期不代表请求一定匹配当前组织、项目和来源环境。它可能属于其他项目、已被删除或撤销、被旧环境变量覆盖，或者请求来自不在允许列表中的 IP。先执行最小 /v1/models 请求比直接重装 SDK 更容易定位。
本地成功，服务器失败，最应该查什么？
优先检查服务器或容器是否注入了正确 Secret、进程是否重启加载新值、服务器公网出口 IP 是否变化，以及代理是否改写 Authorization。不要只确认本地 shell 中变量存在。
使用兼容接口时可以直接复制官方 curl 命令吗？
不能直接复制。兼容接口可能使用不同的 Base URL、/v1 规则、Key、模型 ID 和认证头。应以该服务当前公开文档为准，未核实的地址和模型名不要写进可复制命令。
什么时候应该重新生成 API Key？
如果错误明确指向 Key 不正确、Key 被撤销，或 Key 已经泄露，可以轮换并撤销旧 Key；如果错误是 ip_not_authorized 或组织成员资格问题，单纯换 Key 通常不能解决根因。轮换后要同步更新所有部署配置。
常见问题
401 Unauthorized 和 403 是一回事吗？
不是。401 主要从认证、组织成员关系或 IP 允许列表方向排查；403 需要结合响应继续检查地区、权限或资源访问限制。最终以错误字段和当前官方文档为准。
可以把完整 API Key 打印出来确认吗？
不建议。只检查变量是否存在，或记录经过脱敏的部分字符。如果完整 Key 已进入日志、截图或代码仓库，应先轮换并撤销旧 Key。
为什么 curl 成功，Node.js 或 Python 仍然 401？
这通常说明官方端点和某个凭证本身可用，差异更可能在 SDK 读取的环境变量、Base URL、路径、代理或请求头。应在同一进程中核对这些配置。
IP 允许列表修改后多久再测试？
OpenAI 官方 IP allowlist 文档写明，配置变更后最多等待 15 分钟再测试。测试时必须从实际发起 API 请求的网络路径执行。