OpenAI 错误与恢复

通用HTTP错误与SDK异常见错误码指南。

检查错误

请求错误看HTTP响应；轮次执行或环境初始化失败看事件与已保存状态。

失败对象	检查位置
API请求	HTTP状态及响应`error`对象
轮次	收到`agent.session.turn.failed`后读取轮次，检查`status`与`error`
会话	收到`agent.session.failed`后读取会话，检查`status`与`error`
环境	`agent.session.environment.failed`中的`environment.error`，见沙箱排障

结构化错误的程序判断用 error.code，解释用 error.message；请求验证错误可用 error.param 定位字段。处理器须兼容未知错误码及缺失 param。

Beta API（OpenAI-Beta: agents=v1）的会话 error 是消息字符串或 null，会话失败码需读取伴随SSE error 事件。

API 请求错误

以下错误针对向Agents API发送的请求，与工作开始后产生的轮次错误分开。

HTTP状态及错误码	原因与处理
400 `invalid_request_error`	输入或配置无效、过大。按`error.param`或`error.message`修正，见修正无效输入。
400 `invalid_beta`	`OpenAI-Beta`头无效，检查所用API版本要求。
400 `agent_not_persisted`	`agent_id`属于会话本地智能体。改用已保存智能体ID。
400 `invalid_otlp_endpoint`、`invalid_otlp_header`	追踪端点或请求头无效，修正追踪配置。
401 `unauthorized`；403 `forbidden`	认证失败或无权限，见认证与权限。
404 `not_found_error`、`model_not_found`	请求无权访问资源或模型，检查ID、模型、项目及是否已删除。
409 `conflict_error`	当前资源状态冲突，读错误消息并读取当前状态后再重试。
409 `executor_version_incompatible`	执行器版本不受支持，升级再重试。
424 `mcp_server_startup_failed`	MCP服务器启动失败，检查配置与凭证，见连接排障。
429 `files_api_rate_limit_exceeded`	超过当前用户Files API限额，减少并发，见下节。
500 `internal_error`	服务遇到意外错误，先检查已保存工作再重试，也见服务器错误。
503 `service_unavailable_error`、`server_is_overloaded`	服务或依赖临时不可用、过载，按503指南处理，并先查结果再重试。

Files API 速率限制

创建会话和附加文件可能返回HTTP 429与 files_api_rate_limit_exceeded。Agents API通过Files API检查文件，这会消耗认证用户的Files API额度，每个文件可能分别检查。

来源示例 1（json）：

{
  "error": {
    "type": "rate_limit_error",
    "code": "files_api_rate_limit_exceeded",
    "message": "The Files API rate limit for your user has been exceeded. Reduce the rate of requests that access files, then try again.",
    "param": null
  }
}

减少并发文件请求，以指数退避和有限次数重试。立即重试可能继续耗尽额度。

这一HTTP响应表示操作失败，区别于创建响应成功后会话或轮次再异步失败。按 error.code 判断，不匹配消息文字。

轮次错误

失败轮次具有 status: "failed"，以及含 code、message 的 error。例如模型过载：

来源示例 2（json）：

{
  "code": "server_overloaded",
  "message": "The model is temporarily overloaded. Please retry your request after a brief delay."
}

轮次错误码本身没有HTTP状态；例如轮次用 server_overloaded，HTTP响应可能用 server_is_overloaded。

错误码	原因与处理
`invalid_request`	输入或配置无效，修正消息描述的问题再尝试。
`context_length_exceeded`	输入超过模型上下文，缩小输入；对话过长则用更短摘要新建会话。
`session_budget_exceeded`	会话用量预算已达上限，新建会话继续。
`credit_balance_exhausted`	组织API额度耗尽，按余额指南处理。
`project_spend_limit_exceeded`	项目达到强制支出上限，按支出限制处理。
`organization_spend_limit_exceeded`	组织达到强制支出上限，按组织支出指南处理。
`organization_usage_limit_exceeded`	组织达到OpenAI分配用量上限，见用量限制。
`usage_limit_exceeded`	达到账单或用量上限但无更具体代码，按账单指南处理。
`rate_limit_exceeded`	请求超过速率限制，按重试步骤。
`server_overloaded`	模型服务暂时过载，延迟后只重试未完成工作；持续过载可为后续轮次换模型。
`flex_unavailable`	Flex暂不可用，稍后重试或将后续轮次服务层级改为`default`。
`connection_failed`、`request_timeout`、`server_error`、`internal_error`	连接、超时或服务失败，检查已保存工作，再有限重试。
`authentication_error`	模型访问凭证或权限问题，见认证指南。
`resource_not_found`	模型或资源不可用，重试前检查模型和会话配置。
`sandbox_error`	环境无法完成操作，检查环境错误，修复配置或连接。
`executor_version_incompatible`	执行器无法运行本轮，升级后在未失败会话中重试。
`active_turn_not_steerable`	活动轮次不能接收更多输入，等其结束再发消息。
`cyber_policy`、`misalignment_policy_violation`	安全系统阻止请求，按适用要求审查后再提交修正输入。

会话与环境错误

轮次失败不总等于会话失败。重新读取会话，判断能否继续。requires_action 时先处理所需动作。会话已失败则修正原因，携带仍需的输入新建会话。

错误码	原因与处理
`environment_connection_failed`、`environment_connection_timeout`	沙箱连接失败或太慢，检查启动与网络；自托管环境检查连接配置。
`sandbox_error`	初始化或执行失败，检查命令、包、输入文件及环境错误。
`executor_version_incompatible`	当前执行器不受支持，升级后再新建会话。
`idle_timeout`	托管环境因不活动过期，新建会话并重新提供输入。
`internal_error`	内部失败导致会话或环境未就绪，延迟重试初始化；持续失败联系支持。

恢复

重试暂时性失败

以下用于速率限制、过载、超时和临时服务问题。无效输入、认证和账单限制应先修复，不能盲重试。

确认结果。会话已创建时，读取会话、轮次和已保存项目。轮次活动则继续跟踪，已完成则使用结果。
检查已完成操作。失败轮次可能已经修改文件或调用外部工具，重复工作前确认这些影响。
等待并限制重试。按指数退避，尊重HTTP的 Retry-After，设置次数或截止时间。
重试请求或启动新轮次。HTTP错误先查原操作结果再重试；失败轮次等会话 idle 后发送后续消息，只继续未完成工作，复用已有对话开启新轮次。

轮次完成也检查工具结果。错误类型改变或达到上限时停止自动重试。

修正无效输入

按 error.param 或 error.message 修正字段。大小错误先缩小输入及输出结构或工具结果。智能体配置过大则缩小指令和工具定义，新建会话。

上传问题见处理上传错误。错误指出图像问题时检查图像数据或URL。

流断连

error 事件或流断开不证明轮次最终状态。按恢复断开的流重新连接，重新提交输入前检查已保存工作。

读取到会话 status: "failed" 或收到 agent.session.failed 时停止重连，按会话恢复处理。

持续性错误提交支持请求时，包含请求ID、会话ID和轮次ID。