SpyBara
Go Premium

guides/agents-api/errors.md 2026-09-30 22:59 UTC to 2026-10-01 06:01 UTC

This page contains 24 additions and 18 deletions.

2026
Thu 1 07:01

Errors and recovery

For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.

For general HTTP errors and SDK exceptions, see the shared Error codes guide.

Inspect an error

Check the HTTP response for request errors. For failures during a turn or environment setup, check events and saved state.

Failure Where to look
API request Read the HTTP status and the response's error object.
Turn On agent.session.turn.failed, retrieve the turn and inspect status and error.
Session On agent.session.failed, retrieve the session and inspect status and error.
Environment Read environment.error in agent.session.environment.failed. See sandbox troubleshooting.

For structured errors, use error.code in application logic and error.message to explain the failure. For request validation errors, error.param can identify the field to correct. Handle unknown codes and a missing param without breaking your error handler.

In the beta API (OpenAI-Beta: agents=v1), a session's error is a message string or null. Read the accompanying SSE error event for the session failure code.

API request errors

These errors describe the request to the Agents API. They are separate from the turn errors returned after work starts.

Code Overview
400: invalid_request_error Cause: An input or configuration value is invalid or too large.
Solution: Correct the field identified by error.param or error.message. See Correct invalid input.
400: invalid_beta Cause: The OpenAI-Beta header contains an invalid value.
Solution: Check the header required by the API version you use.
400: agent_not_persisted Cause: The supplied agent_id belongs to a session-local agent.
Solution: Create a saved agent and use its ID.
400: invalid_otlp_endpoint, invalid_otlp_header Cause: The tracing endpoint or headers are invalid.
Solution: Correct your tracing configuration.
401: unauthorized; 403: forbidden Cause: Authentication failed or the caller lacks access.
Solution: See the shared authentication and permission guidance.
404: not_found_error, model_not_found Cause: The resource or model isn't available to this request.
Solution: Check the ID, model, project, and whether the resource was deleted.
409: conflict_error Cause: The operation conflicts with the current resource state.
Solution: Read the message and retrieve the current state before retrying.
409: executor_version_incompatible Cause: The executor version isn't supported.
Solution: Upgrade the executor, then retry.
424: mcp_server_startup_failed Cause: An MCP server failed to start.
Solution: Check the server's configuration and credentials. See Troubleshoot connections.
500: internal_error Cause: The service encountered an unexpected error.
Solution: Check saved work before retrying. See the shared server-error guidance.
503: service_unavailable_error, server_is_overloaded Cause: The service or a dependency is temporarily unavailable or overloaded.
Solution: Follow the shared 503 guidance and check saved work before retrying.

Turn errors

A failed turn has status: "failed" and an error with a code and message. For example, model overload can produce:

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

Turn codes don't have an HTTP status of their own. For example, a failed turn uses server_overloaded; an HTTP response can use server_is_overloaded.

Code Overview
invalid_request Cause: Input or configuration is invalid.
Solution: Correct the input described in the message before trying again.
context_length_exceeded Cause: Input exceeds the model's context window.
Solution: Reduce the input. If the conversation is too long, start a new session with a shorter summary.
session_budget_exceeded Cause: The session reached its usage budget.
Solution: Start a new session to continue.
credit_balance_exhausted Cause: The organization has no API credits remaining.
Solution: See credit balance guidance.
project_spend_limit_exceeded Cause: The project reached its enforced spend limit.
Solution: See project spend limit guidance.
organization_spend_limit_exceeded Cause: The organization reached its enforced spend limit.
Solution: See organization spend limit guidance.
organization_usage_limit_exceeded Cause: The organization reached its OpenAI-assigned usage limit.
Solution: See organization usage limit guidance.
usage_limit_exceeded Cause: A billing or usage limit was reached without a more specific code.
Solution: Follow the shared billing error guidance.
rate_limit_exceeded Cause: Requests exceeded an available rate limit.
Solution: Follow the retry steps.
server_overloaded Cause: The model service is temporarily overloaded.
Solution: Retry the unfinished work after a delay. If overload persists, change the model for later turns.
flex_unavailable Cause: Flex processing is temporarily unavailable.
Solution: Retry later or change the session's service tier to standard processing (default) for later turns.
connection_failed, request_timeout, server_error, internal_error Cause: A connection, timeout, or service failure prevented completion.
Solution: Check saved work, then retry with a limit on attempts.
authentication_error Cause: Model access failed because of credentials or permissions.
Solution: See the shared authentication and permission guidance.
resource_not_found Cause: The requested model or resource is unavailable.
Solution: Check the model and session configuration before retrying.
sandbox_error Cause: The environment couldn't complete an operation.
Solution: Inspect the environment error and fix its configuration or connectivity.
executor_version_incompatible Cause: The executor can't run this turn.
Solution: Upgrade the executor, then retry on the same session if it hasn't failed.
active_turn_not_steerable Cause: The active turn can't accept more input.
Solution: Wait for it to finish before sending another message.
cyber_policy, misalignment_policy_violation Cause: Safety systems blocked the request.
Solution: Review the request against the applicable safety requirements before submitting revised input.

Session and environment errors

A failed turn doesn't always mean the session has failed. Retrieve the session to decide whether you can continue it. If status is requires_action, handle its required actions. If the session has failed, fix the cause and create a new session with the inputs you still need.

Code Overview
environment_connection_failed, environment_connection_timeout Cause: The sandbox couldn't connect or took too long to connect.
Solution: Check executor startup and network access. For self-hosted environments, check the connection setup.
sandbox_error Cause: Sandbox setup or execution failed.
Solution: Inspect setup commands, packages, input files, and the environment error.
executor_version_incompatible Cause: The session's executor version isn't supported.
Solution: Upgrade the executor before creating a new session.
idle_timeout Cause: The hosted environment expired due to inactivity.
Solution: Create a new session and supply the inputs again.
internal_error Cause: An internal failure prevented the session or environment from becoming ready.
Solution: Retry setup after a delay. Contact support if it keeps failing.

Recovery

Retry transient failures

Use this procedure for rate limits, overload, timeouts, and temporary service failures. Fix invalid input, credentials, and billing limits before retrying them.

  1. Check the outcome. If a session was created, retrieve it, the turn, and saved items. If the turn is still active, keep following it. If it completed, use its result.
  2. Check completed actions. A failed turn may already have changed files or called external tools. Confirm those effects before asking the agent to repeat work.
  3. Wait and limit retries. Follow the shared retry guidance, honoring Retry-After on HTTP responses and setting an attempt limit or deadline.
  4. Retry the request or start a new turn. For an HTTP error, retry the original operation after checking its outcome. For a failed turn, wait until the session is idle, then send a follow-up message asking it to continue only unfinished work. This starts a new turn with the existing conversation.

Inspect tool results even when a turn completes. Stop automatic retries if the error changes or the retry limit is reached.

Correct invalid input

Correct the field identified by error.param or error.message before resubmitting.

For size errors, reduce the input and output schema or tool result before retrying. If the agent configuration is too large, create a new session with smaller instructions and tool definitions.

For upload requirements and examples, see Resolve upload errors. If the message identifies an image problem, check the image data or URL.

Disconnected streams

An error event or a disconnected stream doesn't confirm the turn's final state. Follow Recover a disconnected stream to reconnect and check saved work before resubmitting input. If the retrieved session has status: "failed" or you receive agent.session.failed, stop reconnecting and follow the session recovery guidance.

For persistent errors, include the request ID, session ID, and turn ID with your support request.