如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

错误与恢复

了解 Agents API 错误及安全恢复方法。

有关常见 HTTP 错误和 SDK 异常,请参阅通用错误码指南。

查看错误详情

如果请求出错,请检查 HTTP 响应。如果在轮次执行或环境设置过程中发生故障,请检查事件和已保存的状态。

故障类型 查看位置
API 请求 查看 HTTP 状态码和响应中的 error 对象。
轮次 收到 agent.session.turn.failed 事件时,获取该轮次并检查 status 和 error。
会话 收到 agent.session.failed 事件时,获取该会话并检查 status 和 error。
环境 查看 environment.error 字段,该字段位于 agent.session.environment.failed 事件中。请参阅沙盒故障排查。

对于结构化错误,请在应用逻辑中使用 error.code,并使用 error.message 说明失败原因。对于请求验证错误,error.param 可指明需要修正的字段。请确保错误处理程序在遇到未知错误码或缺少 param 时仍能正常运行。

在测试版 API(OpenAI-Beta: agents=v1)中,会话的 error 是消息字符串或 null。要获取会话失败的错误码,请查看随附的 SSE error 事件。

API 请求错误

这些错误涉及发往 Agents API 的请求本身,与任务开始后返回的轮次错误不同。

错误码 说明
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 对您账号的速率限制。
解决方法: 减少并发请求,并按 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 请求配额。每个附加文件都可能需要单独检查。

{
  "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",且 error 包含 code 和 message。例如,模型负载过高时可能返回以下错误:

{
  "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 原因: 安全系统拦截了请求。
解决方法: 对照适用的安全要求检查请求,再提交修改后的输入。

会话和环境错误

轮次失败并不一定表示会话也已失败。请获取会话,判断能否继续使用。如果 status 为 requires_action,请处理该会话要求执行的操作。如果会话已失败,请解决导致失败的问题,再使用仍需保留的输入创建新会话。

错误码 说明
environment_connection_failed、environment_connection_timeout 原因: 沙盒无法建立连接,或建立连接耗时过长。
解决方法: 检查执行器是否正常启动,以及网络是否可访问。如果使用自托管环境,请检查连接设置。
sandbox_error 原因: 沙盒设置或执行失败。
解决方法: 检查设置命令、软件包、输入文件和环境错误。
executor_version_incompatible 原因: 会话使用的执行器版本不受支持。
解决方法: 创建新会话前,请先升级执行器。
idle_timeout 原因: 托管环境因长时间空闲而过期。
解决方法: 创建新会话并重新提供输入。
internal_error 原因: 内部故障导致会话或环境无法就绪。
解决方法: 稍等片刻后重试设置。如果仍然失败,请联系支持团队。

恢复

遇到暂时性故障时重试

遇到速率限制、负载过高、超时或暂时性服务故障时,请按以下步骤操作。如果问题源于无效输入、凭据或账单限额,请先解决相应问题再重试。

  1. 检查操作结果。 如果会话已创建,请获取该会话、轮次及已保存的条目。如果轮次仍在执行,请继续跟踪其进度。如果轮次已完成,请使用其结果。
  2. 检查已完成的操作。 即使轮次失败,也可能已经修改了文件或调用了外部工具。请先确认这些操作产生的影响,再要求智能体重复执行工作。
  3. 等待一段时间并限制重试次数。 请遵循通用的重试指南,按 HTTP 响应中的 Retry-After 指定的时间重试,并设置尝试次数上限或截止时间。
  4. 重试请求或开始新轮次。 如果遇到 HTTP 错误,请先检查原操作的结果,再重试该操作。如果轮次失败,请等到会话状态变为 idle,然后发送后续消息,要求智能体仅继续尚未完成的工作。这样会在现有对话中开始新轮次。

即使轮次已完成,也请检查工具结果。如果错误发生变化或已达到重试次数上限,请停止自动重试。

修正无效输入

重新提交前,请修正 error.param 或 error.message 指明的字段。

如果错误与大小有关,请先缩减输入和输出模式或工具结果的大小,再重试。如果智能体配置过大,请使用更精简的指令和工具定义创建新会话。

有关上传要求和示例,请参阅解决上传错误。如果错误消息指出图像存在问题,请检查图像数据或 URL。

流连接中断

仅凭 error 事件或流连接中断,无法确定轮次的最终状态。请按恢复已断开的流连接中的步骤重新连接,并在重新提交输入前检查已保存的工作。如果获取的会话状态为 status: "failed",或您收到 agent.session.failed 事件,请停止重连,并按会话恢复指南处理。

如果错误持续出现,请在联系支持团队时提供请求 ID、会话 ID 和轮次 ID。