OpenAI API 错误响应排查保姆级指南

【免费下载链接】openai-openapiOpenAPI specification for the OpenAI API项目地址: https://gitcode.com/GitHub_Trending/op/openai-openapi

第一次调用 OpenAI API，终端吐回401 Unauthorized，错误体里一行invalid_api_key——你盯着屏幕，多半先怀疑密钥，但方向猜错，排查会卡一整天。这份 OpenAI API 错误处理指南，教你把 openapi.yaml 里的错误结构当成排查地图：先按状态码分流，再逐字段读error对象，最后给 429 限流配好退避重试。

看状态码分流：4xx 和 5xx 各走一条路

OpenAI 的所有接口失败都会返回统一的 JSON 错误体，但修复路径完全不同：4xx 是"你做错了什么"，改请求；5xx 是"它出了问题"，等和重试。先盯状态码，再进错误体，能省掉一半瞎忙。

状态码是 401 吗？先怀疑密钥再怀疑代码

现象很好认：401，code是invalid_api_key。定位顺序固定两步：先确认请求头里真的带上了Authorization: Bearer sk-...，再确认这个 key 没被吊销。下面这条 curl 是最小复现，直接在你机器上跑一遍最省事：

curl https://api.openai.com/v1/models \ -H "Authorization: Bearer $OPENAI_API_KEY"

跑完如果返回 200 和一份模型列表，说明密钥活着，问题在别处（比如代码里拼请求头时漏了 Bearer 前缀）；如果还是 401，基本可以断定 key 本身失效了，去控制台重新生成一个再替换。

状态码是 400？拿 spec 对照参数

400 配invalid_request_error，意思是请求体本身不合规：model写了不存在的名字、messages里的某条缺role、JSON 多了个逗号……这时候别猜，直接翻 openapi.yaml 里对应接口的 schema，把你提交的字段和定义逐项对一遍。param字段通常会直接点名坏掉的参数，顺着它找最快。

状态码是 429？先读 Retry-After 再谈重试

429 说明你撞了速率限制或配额上限。正确的姿势不是立即重发，而是读响应头里的Retry-After（单位秒），按指数退避往后推：

import time attempt, max_retry = 0, 3 while attempt < max_retry: resp = post_chat_request() # 你的请求封装 if resp.status_code != 429: break wait = int(resp.headers.get("Retry-After", 2 ** attempt)) time.sleep(wait) # 1s -> 2s -> 4s 递增 attempt += 1

这段伪代码证明一件事：限流不是错误，是节奏问题——退避到窗口期过了再发，大概率一次过，比裸重试既省配额，也不容易触发更严的惩罚。

状态码是 5xx？延迟重试而不是硬刚

500、503属于服务端故障，你改什么参数都没用。策略是：几分钟后重试、把输入适当裁短、连续失败就停手观察。如果长响应中途直接断流、连完整错误体都没有，多半是超时中断，重新发起请求即可，不必反复换参数试。

逐字段核对 error 对象，锁定真正根因

分流完之后，真正定位靠的是错误体本身。规范里对它的定义不长，但信息密度很高，值得当字典用。

type 定大类，code 定具体原因

一次 401 的完整响应长这样：

{ "error": { "message": "Incorrect API key provided: sk-xxx...xxx. You can find your API key in the dashboard.", "type": "invalid_request_error", "param": null, "code": "invalid_api_key" } }

它证明：type负责粗分类，code才是一级细分（invalid_api_key、model_not_found各管一段）。写日志和做告警时应该用code而不是message，因为message是给人看的自然语言，随时可能微调。

param 非 null 时说明什么

param是定位利器：它非 null 时，指的就是你请求里具体哪个字段越界，比如max_tokens；它是 null，说明问题发生在请求之外——认证、限流、服务端故障这一类。看到 null 就别再翻请求体了。

用 ErrorResponse 定义验证响应来源

openapi.yaml 中Errorschema 声明type、message、param、code四个字段全部 required。拿这条当判据：如果你的错误体缺了其中任何一个字段，它多半不是 OpenAI 返回的，而是中间网关、代理或 SDK 自己抛的——排查方向立刻从"API 用错"变成"链路检查"。

把排查动作固化成两道检查

回到开头那个 401 的瞬间，你现在手里的动作顺序是固定的：状态码分流 → 读code和param→ 对 spec 核对 → 决定改配置还是重试。下次报错，把下面两行贴进你的值班手册就够了：

跑通一遍你会发现，错误处理拼的不是记忆力，是顺序——状态码先于消息，code 先于猜测，退避先于硬刚。

【免费下载链接】openai-openapiOpenAPI specification for the OpenAI API项目地址: https://gitcode.com/GitHub_Trending/op/openai-openapi