有关常见 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 |
原因: 内部故障导致会话或环境无法就绪。 解决方法: 稍等片刻后重试设置。如果仍然失败,请联系支持团队。 |
恢复
遇到暂时性故障时重试
遇到速率限制、负载过高、超时或暂时性服务故障时,请按以下步骤操作。如果问题源于无效输入、凭据或账单限额,请先解决相应问题再重试。
- 检查操作结果。 如果会话已创建,请获取该会话、轮次及已保存的条目。如果轮次仍在执行,请继续跟踪其进度。如果轮次已完成,请使用其结果。
- 检查已完成的操作。 即使轮次失败,也可能已经修改了文件或调用了外部工具。请先确认这些操作产生的影响,再要求智能体重复执行工作。
- 等待一段时间并限制重试次数。 请遵循通用的重试指南,按 HTTP 响应中的
Retry-After指定的时间重试,并设置尝试次数上限或截止时间。 - 重试请求或开始新轮次。 如果遇到 HTTP 错误,请先检查原操作的结果,再重试该操作。如果轮次失败,请等到会话状态变为
idle,然后发送后续消息,要求智能体仅继续尚未完成的工作。这样会在现有对话中开始新轮次。
即使轮次已完成,也请检查工具结果。如果错误发生变化或已达到重试次数上限,请停止自动重试。
修正无效输入
重新提交前,请修正 error.param 或 error.message 指明的字段。
如果错误与大小有关,请先缩减输入和输出模式或工具结果的大小,再重试。如果智能体配置过大,请使用更精简的指令和工具定义创建新会话。
有关上传要求和示例,请参阅解决上传错误。如果错误消息指出图像存在问题,请检查图像数据或 URL。
流连接中断
仅凭 error 事件或流连接中断,无法确定轮次的最终状态。请按恢复已断开的流连接中的步骤重新连接,并在重新提交输入前检查已保存的工作。如果获取的会话状态为 status: "failed",或您收到 agent.session.failed 事件,请停止重连,并按会话恢复指南处理。
如果错误持续出现,请在联系支持团队时提供请求 ID、会话 ID 和轮次 ID。