OpenAI API 错误处理避坑指南401、429 与 5xx 一次排查到位【免费下载链接】openai-openapiOpenAPI specification for the OpenAI API项目地址: https://gitcode.com/GitHub_Trending/op/openai-openapi昨晚发版后线上开始连续吐 401本地用同一个 key 却一切正常。你盯着终端第一反应不是加日志而是先问自己到底是密钥的事还是请求头的事OpenAI 的错误处理核心不是看到错误而是让失败变得可解释、可恢复。openai-openapi 仓库把 OpenAI REST API 完整写成了 OpenAPI 3.1 规范OpenAPI 3.1 是目前主流版本的接口描述标准机器可读、可生成客户端端点、认证方式、参数与响应结构都能查到——排查参数类报错时它就是你的对照字典。拿到错误响应后的速查表所有失败响应都带一个error对象四要素固定code、message、param、type。code给程序分支判断message给人看param指向具体出错的字段type标明大类。信号大概率原因第一反应401 authentication_error密钥无效 / 请求头没带对先查凭证别碰参数400 invalid_request_error请求体不符合规范对照 openapi.yaml 逐项核对429 rate_limit_error限流或配额不足读Retry-After响应头退避重试5xx internal_server_error服务端临时故障短暂等待后重试排查优先级一如何快速定位 401 认证失败401 优先查因为密钥一错后面所有排查都是白费。三步走确认 key 本身有效用官方 SDK 拉一下模型列表client.models.list()能返回结果说明密钥没问题把怀疑转向请求头。检查请求头必须是Authorization: Bearer sk-...少了Bearer前缀、多了空格或引号都会失败。curl https://api.openai.com/v1/chat/completions \ -H Authorization: Bearer sk-xxxxxxxx \ -H Content-Type: application/json \ -d {model:gpt-4o,messages:[{role:user,content:hi}]}检查环境差异本地能跑、线上挂十有八九是环境变量在 CI 或容器里被截断、拼接错了。去平台 API keys 页面确认 key 没有被吊销吊销了就重新生成替换。排查优先级二400 参数错误怎么对照着改400 的意思很简单请求不符合规范。高频原因就三个——JSON 语法错误多逗号、引号没闭合、model名字拼错或当前账号无权访问、messages里缺role或content。动作顺序建议先用 JSON 校验工具如 JSONLint确认语法再对照 openapi.yaml 里对应接口的参数定义逐项比对模型名拿不准时同样用 models 列表接口确认账号下实际可用的模型别凭记忆写。排查优先级三429 限流重试怎么写429 是客户端错误里唯一等一等就好的类型。重试逻辑要遵守一个原则优先听服务端的Retry-After响应头它告诉你具体等几秒没有再退到指数退避等待时间每次翻倍1s → 2s → 4s并且必须设重试上限。for attempt in range(3): resp post(url, jsonpayload) if resp.status_code ! 429: break wait int(resp.headers.get(Retry-After, 2 ** attempt)) time.sleep(wait)重试到上限仍是 429问题多半不在频率而在配额去用量面板看剩余额度必要时升级套餐或降低调用并发。排查优先级四5xx 值不值得你修服务端错误通常是暂时性的先等几分钟再试同时可以简化请求缩短输入、换更小的模型降低触发概率。顺手看一眼官方状态页确认是不是正在故障期。对 5xx 的处理姿态静默重试 给用户友好提示重试耗尽再告警别让一条瞬时故障打出告警风暴。日志与重试策略避坑清单4xx 不要无脑重试参数错了重试一万次也是同一个错。只有 429 和 5xx 值得自动重试。日志留四样东西状态码、error对象全字段、请求参数脱敏、时间与环境。密钥永远别进日志Authorization头、截图、诊断输出都要先脱敏再落盘。上线前自查5 分钟排查清单照着勾一遍能挡掉绝大多数线上错误密钥来自环境变量请求头带Bearer前缀本地 / 线上各验证一次model名与 openapi.yaml 里的定义、账号权限一致429 重试遵守Retry-After且有次数上限5xx 有退避重试不直接裸抛给用户日志记录状态码 code/type/param/message且已脱敏勾完最后一项你的错误处理才算闭环报错时能秒级定位恢复时不用人肉盯。【免费下载链接】openai-openapiOpenAPI specification for the OpenAI API项目地址: https://gitcode.com/GitHub_Trending/op/openai-openapi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考