401 先查 API Key 和 Authorization 是否有效、是否被删除以及线上是否读取了正确环境变量；403 再查 organization、project、模型权限、Restricted Key 和资源归属。API Credits 余额不能修复无效 Key。不要打印、复制或提交完整 secret。
官方参考（2026-10-28 核对）：OpenAI：Incorrect API key · API Platform 项目与资源边界 · API Key 权限
先看状态码，不要把所有错误都叫“Key 无效”
| 现象 | 优先判断 | 第一步 |
|---|---|---|
| 401 / Incorrect API key | Key 错误、被删除、空格、变量未加载或 Authorization 缺失 | 确认程序读取的变量存在且对应当前有效 Key，不打印值 |
| 403 / permission denied | project、organization、模型权限或 Restricted 规则不匹配 | 确认资源所属 project 与 Key 作用域 |
| 429 / insufficient_quota | 余额、支出上限、组织限制或速率限制 | 查看 Credits、Usage 和 error.code |
| 浏览器暴露 Key | 客户端架构不安全，不是简单重试问题 | 撤销 Key，改为后端代理 |
第一步：确认程序真的读取了正确的 Key
- 在 API Platform 的 API Keys 页面确认该 Key 仍存在，且不是刚刚删除或轮换前的旧 Key。
- 确认请求使用的是同一个变量名，例如
OPENAI_API_KEY；检查变量是否为空、前后是否有空格，但不要输出变量值。 - 确认代码没有同时读取两个 Key，也没有在 SDK 配置与自定义
Authorizationheader 中混用不同密钥。 - 更新密钥后重启本地进程、容器、Serverless Function 或部署；只改控制台变量而不重新部署，旧进程可能仍在使用旧值。
- 如果密钥曾出现在仓库、日志、前端 bundle、截图或聊天中，按泄露流程撤销，不要继续测试旧 Key。
OpenAI 的 Incorrect API key 指南建议核对实际使用的 Key、避免同时使用两个不同 Key，并确认 organization 设置。
本地、Vercel 和 CI/CD 的安全检查方式
本地开发
使用未提交的 .env.local 或系统环境变量，并加入 .gitignore。调试时只打印“变量已设置/未设置”，绝不打印完整值。
Vercel、云主机与容器
确认变量配置在实际运行环境（Preview 或 Production），变量名与代码一致，更新后重新部署。不要把 API Key 放到 NEXT_PUBLIC_*、浏览器 bundle、HTML、客户端 JavaScript 或 URL 查询参数。
GitHub Actions 与其他 CI/CD
使用 Secrets 注入，检查 workflow 是否把环境变量写入日志。若日志曾输出密钥，应立即撤销，并清理构建产物和缓存。
401：Invalid API Key 的排查顺序
- 确认请求头格式为
Authorization: Bearer $OPENAI_API_KEY，没有把变量名当成字面量，也没有多余引号或换行。 - 确认 SDK、curl 或自定义 HTTP 客户端只设置一个认证来源。
- 确认部署读取的是当前环境的 Key，而不是本地、Preview 或旧 organization 的变量。
- 确认 Key 没有被删除、撤销或轮换；遗失或疑似泄露时创建新 Key。
- 用占位符测试配置逻辑，不要在文章、Issue 或聊天中贴真实 secret。
curl https://api.openai.com/v1/models \
-H "Authorization: Bearer $OPENAI_API_KEY"示例只展示变量引用，不包含真实密钥。
403：权限、project 和 organization 排查
- 确认 Key 属于当前请求使用的 project；项目级 Key 不能随意访问另一个项目的资源。
- 确认组织选择器没有切换到其他 organization；多组织账户尤其容易出现“本地成功、线上失败”。
- 查看 Key 的权限类型：Restricted 是否禁止了当前 endpoint 或动作，Read Only 是否被用于写入/调用场景。
- 确认模型或资源在该 project 可用，并检查项目成员角色、模型访问和支出配置。
- 如果请求带 organization/project 标识，逐项核对其值；不要把 ChatGPT 账号 ID 当作 API organization ID。
项目成员、资源、API Keys、模型访问、Usage 和 spend limits 都可能绑定到 project；资源归属不匹配时，单纯重建密钥不一定解决 403。
有 Credits 余额仍报错，先看 error.code
API Key 认证、项目权限、账单余额和速率限制是不同层。API Credits 页面适合处理预付余额和自动充值；API Key 安全页面适合创建、权限和轮换。不要看到 insufficient_quota 就重新订阅 ChatGPT Plus，也不要看到 401 就重复充值。
- 401：先修复认证材料与环境变量。
- 403：先修复 project、organization 或权限。
- 429/insufficient_quota：再检查 Credits、Usage、支出上限和速率限制。
怀疑泄露时的应急步骤
- 立即删除或撤销泄露 Key。
- 创建替代 Key，更新服务器、Vercel、容器和 CI/CD Secrets。
- 重新部署并确认请求恢复。
- 检查 Usage、Billing、日志和仓库历史中的异常调用。
- 联系官方支持时只提供项目、时间、错误类型和遮挡后的证据。
不要发送完整 API Key、银行卡号、CVC、账号密码、验证码或浏览器 Cookie。API Key 是认证凭据，不是排障截图。
常见问题
OpenAI API 报 Incorrect API key 怎么办？
先确认程序读取的是当前有效密钥，而不是旧密钥、被删除的密钥或另一环境的密钥；不要把完整密钥粘贴到聊天或工单。重新创建并安全替换密钥后，再重启服务验证。
为什么同一个 API Key 在本地可以、线上不行？
常见原因是线上环境变量未配置、变量名不一致、部署后未重启、读取了 Preview 而不是 Production，或线上使用了另一套 organization/project。只检查变量是否存在，不要打印 secret 内容。
API 401 和 403 有什么区别？
401 通常先查认证材料本身：Key 错误、过期、删除、空格或请求没有携带 Authorization。403 更应查 project、organization、模型权限、Restricted Key 规则和资源归属。具体错误正文优先于笼统猜测。
OpenAI API Key 需要同时设置 Organization ID 吗？
不一定。许多请求只需要有效 API Key；当账号属于多个 organization，或项目资源归属明确时，按官方认证方式指定正确 organization/project。不要把 ChatGPT 账号 ID 当作 API organization ID。
有 API Credits 余额却报 401 怎么办？
Credits 只解决账单或余额，不会修复无效认证。先修复 API Key、Authorization header、organization/project 和权限；如果错误变成 429 或 insufficient_quota，再查余额、支出限制和速率限制。
怀疑 API Key 泄露后还能继续测试吗？
不建议。先删除或撤销泄露密钥，创建替代密钥并更新所有环境，再检查 Usage、Billing 和日志。不要只改变量名，也不要把旧密钥留在仓库历史或构建产物中。
先定位错误层级，再改配置
401 主要看认证，403 主要看权限和资源归属，429 才进入余额与限流排查。按层处理能避免重复充值、乱换 Key 和泄露更多凭据。
生产服务需要独立系统身份时，请参考 OpenAI API Service Account 创建与轮换指南。
遇到服务端错误或连接超时时，请参考OpenAI API 500/503与超时排查。