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 吗先怀疑密钥再怀疑代码现象很好认401code是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 核对 → 决定改配置还是重试。下次报错把下面两行贴进你的值班手册就够了看到什么先做什么401 /invalid_api_keycurl 单测密钥再查 Bearer 请求头429 限流读Retry-After指数退避最多 3 次跑通一遍你会发现错误处理拼的不是记忆力是顺序——状态码先于消息code 先于猜测退避先于硬刚。【免费下载链接】openai-openapiOpenAPI specification for the OpenAI API项目地址: https://gitcode.com/GitHub_Trending/op/openai-openapi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考