OpenAI API 错误处理4 类高频异常的定位路径与处置动作【免费下载链接】openai-openapiOpenAPI specification for the OpenAI API项目地址: https://gitcode.com/GitHub_Trending/op/openai-openapiOpenAI API 错误处理这件事本质上是在做两件事先判断错误属于哪一类再决定下一个动作。本文以排障动作为主线把 400、401、429、500 这四类高频异常各自的诱因与处置方式一次讲清示例参数均以本仓库的 openapi.yaml 规范为准。一张速查表从状态码到处置动作收到报错后不要通读错误文案先拿状态码对表。下表覆盖绝大多数线上场景状态码含义高频诱因第一步动作400 Bad Request参数校验未通过必填字段缺失、messages结构不对、JSON 语法错误、模型不可用对照规范逐项核对请求体401 Unauthorized认证失败密钥缺失、拼错、已吊销检查Authorization请求头必要时重新生成密钥429 Too Many Requests触发速率限制Rate Limit或配额用尽瞬时请求量过高、月度配额耗尽读取Retry-After头并退避重试500 Internal Server Error服务端内部异常临时故障、未处理的内部异常延迟重试同时准备降级方案规律是4xx 基本都指向你自己发出去的那次请求5xx 指向上游服务。429是个特例——请求本身没问题只是现在不行所以它需要的是等待与重试而不是改代码逻辑。解剖报错状态码之外看error对象OpenAI 的错误响应统一包在 JSON 响应体的error对象里。以密钥无效为例响应中的type为invalid_request_errormessage会写明 Incorrect API key provided 并给出密钥管理入口提示code为invalid_api_key。程序化排障时重点盯住以下四个字段字段作用示例值message人可读的错误描述直接指出问题所在Incorrect API key provided: sk-xxx...type错误大类用于路由到不同处理分支invalid_request_errorparam出错的参数名没有则为nullnullcode机器可读错误码是自动处理最可靠的判断依据invalid_api_key实践中建议用code做分支判断、用message打日志。code集合稳定适合写进if/elifmessage文案可能随版本微调不适合做精确匹配。401 认证失败三步排查认证失败几乎只有三个来源按出现频率排序依次排查密钥本身的问题先去平台控制台的密钥管理页确认密钥是否存在、是否被吊销。丢失或过期就直接新建旧密钥当场停用。请求头没带对确认请求携带Authorization: Bearer YOUR_API_KEY注意Bearer与密钥之间有一个空格且不要多加引号。用一条最小化请求即可验证通路是否正常curl https://api.openai.com/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \ -d {model: gpt-4o, messages: [{role: user, content: Hello}]}这条命令只发最简请求返回 200 说明密钥与网络通路都没问题问题出在你业务代码的鉴权环节仍返回 401 则回到第 1 步换密钥。环境间密钥不一致CI、容器、多环境配置里最容易混入旧密钥。用env或配置中心核对实际生效的值而不是你以为的值。400 参数被拒对着规范逐项核对400 的排查顺序是先查可用性再查结构最后查语法模型是否可用model指定的模型可能不存在或当前账号没有访问权限。先列一遍当前密钥可用的模型清单from openai import OpenAI client OpenAI(api_keyYOUR_API_KEY) models client.models.list() print([model.id for model in models.data])如果目标模型不在这个列表里400 就与参数无关了——要么换模型要么申请权限。消息结构是否符合约定messages数组的每个元素必须包含role与content且role取值限定在system/user/assistant等合法值内。对照 openapi.yaml 中ChatCompletionRequest的定义逐字段检查比凭记忆猜要快得多。JSON 本身是否合法多一个逗号、少一个引号都会让请求体无法解析。把请求体粘进任意 JSON 校验工具如 JSONLint确认语法再发请求。429 限流指数退避重试怎么写 429 的响应头里通常带Retry-After告知建议等待秒数。没有这个头时用指数退避第 n 次重试前等待 2 的 n 次方秒。关键是给重试设上限避免在服务持续限流时空转import time import requests url https://api.openai.com/v1/chat/completions headers {Authorization: Bearer YOUR_API_KEY, Content-Type: application/json} data {model: gpt-4o, messages: [{role: user, content: Hello}]} retry_count, max_retries 0, 3 while retry_count max_retries: response requests.post(url, headersheaders, jsondata) if response.status_code ! 429: return response wait int(response.headers.get(Retry-After, 2 ** retry_count)) time.sleep(wait) retry_count 1 return response若退避重试耗尽仍持续 429问题多半不在速率而在配额到平台的用量页面核对本月消耗额度耗尽就只能升级套餐或联系支持扩容代码层面无法自救。500 服务端错误重试、降级、查状态500 与 502 这类服务端错误请求本身大概率没有错处置顺序是等待后重试多数 500 是瞬时故障间隔几分钟后原样重发即可。把 5xx 纳入自动重试分支与 4xx 严格分开——4xx 重试一百次结果也不变白白浪费配额。降级请求若同一请求反复 500试着缩短输入文本或换用更轻量的模型例如以gpt-3.5-turbo替代gpt-4o验证是否是某类特殊输入触发了内部异常。确认上游状态如果所有请求成片 5xx基本可以判定是平台侧故障到 OpenAI 官方状态页status.openai.com查看事件通告等待恢复即可此时继续重试只会拖慢自己的系统。把排障动作固化日志、分类与文档一次性排障靠经验长期稳定靠机制日志要素每条错误日志应包含脱敏后的请求参数密钥必须打码、状态码、error对象全文、时间戳与环境标识。事后复现 429 或 500 时这些信息缺一不可。分类策略4xx 走立即修复路径——改参数、换密钥不做自动重试429 走退避重试5xx 走带上限的自动重试加告警。把这条规则写进统一的中间件或客户端封装避免每个业务函数各写一套。对照权威来源遇到拿不准的code直接查 OpenAI 官方错误码文档Error Codes for the API 一节每个 code 都有对应说明与处理建议。上线前错误处理自查清单发布前过一遍这份清单能挡掉绝大多数线上事故所有请求出口都有状态码判断4xx / 429 / 5xx 分别走不同分支429 与 5xx 的重试带次数上限且等待采用指数退避错误日志包含状态码、error对象全文与脱敏参数可直接用于复现API 密钥通过环境变量或密钥管理注入未硬编码进代码仓库关键链路配置了 5xx 连续出现时的告警而不是只靠用户反馈请求体结构定期与 openapi.yaml 规范比对避免接口字段更新后悄然失效错误不会消失但它应该变得可预期。把上面这套状态码分类—error字段定位—分类处置的流程跑顺之后下一次 401 或 429 出现你需要的只是查表和执行而不是从头猜起。【免费下载链接】openai-openapiOpenAPI specification for the OpenAI API项目地址: https://gitcode.com/GitHub_Trending/op/openai-openapi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考