Documentation 2026-09-30 22:59 UTC to 2026-10-01 06:01 UTC

153 153 

154See the [Agents API reference](https://developers.openai.com/api/reference/resources/beta/subresources/agents) for configuration fields and values. For setup, see [Functions](https://developers.openai.com/api/docs/guides/agents-api/tools/functions), [Computer use](https://developers.openai.com/api/docs/guides/agents-api/tools/computer-use), [MCP connections](https://developers.openai.com/api/docs/guides/agents-api/tools/mcp), or [Multi-agent delegation](https://developers.openai.com/api/docs/guides/agents-api/multi-agent).154See the [Agents API reference](https://developers.openai.com/api/reference/resources/beta/subresources/agents) for configuration fields and values. For setup, see [Functions](https://developers.openai.com/api/docs/guides/agents-api/tools/functions), [Computer use](https://developers.openai.com/api/docs/guides/agents-api/tools/computer-use), [MCP connections](https://developers.openai.com/api/docs/guides/agents-api/tools/mcp), or [Multi-agent delegation](https://developers.openai.com/api/docs/guides/agents-api/multi-agent).

155 155 

156### Configuration size

157 

158Keep the combined size of your instructions and tool configuration below 4 MiB (4,194,304 bytes), leaving a little room for Agents API metadata. If session startup fails because this configuration is too large, create a new session with smaller instructions and tool configuration.

159 

160Files uploaded to the environment follow separate [file limits](https://developers.openai.com/api/docs/guides/agents-api/environments/files#file-limits).

161 

156## Reuse an agent across sessions162## Reuse an agent across sessions

157 163 

158Save an agent to reuse its configuration across sessions. Create it once, then pass its ID as `agent_id` when starting each session:164Save an agent to reuse its configuration across sessions. Create it once, then pass its ID as `agent_id` when starting each session:

30[turn errors](#turn-errors) returned after work starts.30[turn errors](#turn-errors) returned after work starts.

31 31 

32| Code | Overview |32| Code | Overview |

33| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |33| -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

34| 400: `invalid_request_error` | **Cause:** An input or configuration value is invalid. <br /> **Solution:** Correct the field identified by `error.param` or `error.message`. See [Correct invalid input](#correct-invalid-input). |34| 400: `invalid_request_error` | **Cause:** An input or configuration value is invalid or too large. <br /> **Solution:** Correct the field identified by `error.param` or `error.message`. See [Correct invalid input](#correct-invalid-input). |

35| 400: `invalid_beta` | **Cause:** The `OpenAI-Beta` header contains an invalid value. <br /> **Solution:** Check the header required by the API version you use. |35| 400: `invalid_beta` | **Cause:** The `OpenAI-Beta` header contains an invalid value. <br /> **Solution:** Check the header required by the API version you use. |

36| 400: `agent_not_persisted` | **Cause:** The supplied `agent_id` belongs to a session-local agent. <br /> **Solution:** [Create a saved agent](https://developers.openai.com/api/docs/guides/agents-api/configuration#reuse-an-agent-across-sessions) and use its ID. |36| 400: `agent_not_persisted` | **Cause:** The supplied `agent_id` belongs to a session-local agent. <br /> **Solution:** [Create a saved agent](https://developers.openai.com/api/docs/guides/agents-api/configuration#reuse-an-agent-across-sessions) and use its ID. |

37| 400: `invalid_otlp_endpoint`, `invalid_otlp_header` | **Cause:** The tracing endpoint or headers are invalid. <br /> **Solution:** Correct your [tracing configuration](https://developers.openai.com/api/docs/guides/agents-api/tracing). |37| 400: `invalid_otlp_endpoint`, `invalid_otlp_header` | **Cause:** The tracing endpoint or headers are invalid. <br /> **Solution:** Correct your [tracing configuration](https://developers.openai.com/api/docs/guides/agents-api/tracing). |

38| 401: `unauthorized`; 403: `forbidden` | **Cause:** Authentication failed or the caller lacks access. <br /> **Solution:** Check the API key and its organization, project, and resource permissions. |38| 401: `unauthorized`; 403: `forbidden` | **Cause:** Authentication failed or the caller lacks access. <br /> **Solution:** See the shared [authentication and permission guidance](https://developers.openai.com/api/docs/guides/error-codes#python-library-error-types). |

39| 404: `not_found_error`, `model_not_found` | **Cause:** The resource or model isn't available to this request. <br /> **Solution:** Check the ID, model, project, and whether the resource was deleted. |39| 404: `not_found_error`, `model_not_found` | **Cause:** The resource or model isn't available to this request. <br /> **Solution:** Check the ID, model, project, and whether the resource was deleted. |

40| 409: `conflict_error` | **Cause:** The operation conflicts with the current resource state. <br /> **Solution:** Read the message and retrieve the current state before retrying. |40| 409: `conflict_error` | **Cause:** The operation conflicts with the current resource state. <br /> **Solution:** Read the message and retrieve the current state before retrying. |

41| 409: `executor_version_incompatible` | **Cause:** The executor version isn't supported. <br /> **Solution:** Upgrade the executor, then retry. |41| 409: `executor_version_incompatible` | **Cause:** The executor version isn't supported. <br /> **Solution:** Upgrade the executor, then retry. |

42| 424: `mcp_server_startup_failed` | **Cause:** An MCP server failed to start. <br /> **Solution:** Check the server's configuration and credentials. See [Troubleshoot connections](https://developers.openai.com/api/docs/guides/agents-api/tools/mcp#troubleshoot-connections). |42| 424: `mcp_server_startup_failed` | **Cause:** An MCP server failed to start. <br /> **Solution:** Check the server's configuration and credentials. See [Troubleshoot connections](https://developers.openai.com/api/docs/guides/agents-api/tools/mcp#troubleshoot-connections). |

43| 500: `internal_error` | **Cause:** The service encountered an unexpected error. <br /> **Solution:** [Retry your request](#retry-transient-failures) after a brief wait and contact us if the issue persists. Check the [status page](https://status.openai.com/). |43| 500: `internal_error` | **Cause:** The service encountered an unexpected error. <br /> **Solution:** [Check saved work before retrying](#retry-transient-failures). See the shared [server-error guidance](https://developers.openai.com/api/docs/guides/error-codes#api-errors). |

44| 503: `service_unavailable_error`, `server_is_overloaded` | **Cause:** The service or a dependency is temporarily unavailable or overloaded. <br /> **Solution:** Honor `Retry-After` when present, then retry with increasing delays. |44| 503: `service_unavailable_error`, `server_is_overloaded` | **Cause:** The service or a dependency is temporarily unavailable or overloaded. <br /> **Solution:** Follow the shared [503 guidance](https://developers.openai.com/api/docs/guides/error-codes#api-errors) and [check saved work before retrying](#retry-transient-failures). |

45 45 

46## Turn errors46## Turn errors

47 47 

63| `invalid_request` | **Cause:** Input or configuration is invalid. <br /> **Solution:** Correct the input described in the message before trying again. |63| `invalid_request` | **Cause:** Input or configuration is invalid. <br /> **Solution:** Correct the input described in the message before trying again. |

64| `context_length_exceeded` | **Cause:** Input exceeds the model's context window. <br /> **Solution:** Reduce the input. If the conversation is too long, start a new session with a shorter summary. |64| `context_length_exceeded` | **Cause:** Input exceeds the model's context window. <br /> **Solution:** Reduce the input. If the conversation is too long, start a new session with a shorter summary. |

65| `session_budget_exceeded` | **Cause:** The session reached its usage budget. <br /> **Solution:** Start a new session to continue. |65| `session_budget_exceeded` | **Cause:** The session reached its usage budget. <br /> **Solution:** Start a new session to continue. |

66| `credit_balance_exhausted` | **Cause:** The organization has no API credits remaining. <br /> **Solution:** Add credits before retrying. |66| `credit_balance_exhausted` | **Cause:** The organization has no API credits remaining. <br /> **Solution:** See [credit balance guidance](https://developers.openai.com/api/docs/guides/error-codes#api-errors). |

67| `project_spend_limit_exceeded` | **Cause:** The project reached its enforced spend limit. <br /> **Solution:** Increase or remove the project's [spend limit](https://developers.openai.com/api/docs/guides/spend-limits). |67| `project_spend_limit_exceeded` | **Cause:** The project reached its enforced spend limit. <br /> **Solution:** See [project spend limit guidance](https://developers.openai.com/api/docs/guides/error-codes#api-errors). |

68| `organization_spend_limit_exceeded` | **Cause:** The organization reached its enforced spend limit. <br /> **Solution:** Increase or remove the organization's [spend limit](https://developers.openai.com/api/docs/guides/spend-limits). |68| `organization_spend_limit_exceeded` | **Cause:** The organization reached its enforced spend limit. <br /> **Solution:** See [organization spend limit guidance](https://developers.openai.com/api/docs/guides/error-codes#api-errors). |

69| `organization_usage_limit_exceeded` | **Cause:** The organization reached its OpenAI-assigned usage limit. <br /> **Solution:** Request a higher [usage limit](https://developers.openai.com/api/docs/guides/rate-limits#usage-tiers). |69| `organization_usage_limit_exceeded` | **Cause:** The organization reached its OpenAI-assigned usage limit. <br /> **Solution:** See [organization usage limit guidance](https://developers.openai.com/api/docs/guides/error-codes#api-errors). |

70| `usage_limit_exceeded` | **Cause:** A billing or usage limit was reached without a more specific code. <br /> **Solution:** Check credits, spend limits, and usage limits before retrying. |70| `usage_limit_exceeded` | **Cause:** A billing or usage limit was reached without a more specific code. <br /> **Solution:** Follow the shared [billing error guidance](https://developers.openai.com/api/docs/guides/error-codes#api-errors). |

71| `rate_limit_exceeded` | **Cause:** Requests exceeded an available rate limit. <br /> **Solution:** Reduce the request rate and [retry with increasing delays](#retry-transient-failures). |71| `rate_limit_exceeded` | **Cause:** Requests exceeded an available rate limit. <br /> **Solution:** Follow the [retry steps](#retry-transient-failures). |

72| `server_overloaded` | **Cause:** The model service is temporarily overloaded. <br /> **Solution:** [Retry the unfinished work after a delay](#retry-transient-failures). If overload persists, [change the model for later turns](https://developers.openai.com/api/docs/guides/agents-api/configuration#update-settings-for-an-existing-session). |72| `server_overloaded` | **Cause:** The model service is temporarily overloaded. <br /> **Solution:** [Retry the unfinished work after a delay](#retry-transient-failures). If overload persists, [change the model for later turns](https://developers.openai.com/api/docs/guides/agents-api/configuration#update-settings-for-an-existing-session). |

73| `flex_unavailable` | **Cause:** Flex processing is temporarily unavailable. <br /> **Solution:** Retry later or [change the session's service tier](https://developers.openai.com/api/docs/guides/agents-api/configuration#update-settings-for-an-existing-session) to standard processing (`default`) for later turns. |73| `flex_unavailable` | **Cause:** Flex processing is temporarily unavailable. <br /> **Solution:** Retry later or [change the session's service tier](https://developers.openai.com/api/docs/guides/agents-api/configuration#update-settings-for-an-existing-session) to standard processing (`default`) for later turns. |

74| `connection_failed`, `request_timeout`, `server_error`, `internal_error` | **Cause:** A connection, timeout, or service failure prevented completion. <br /> **Solution:** Check saved work, then [retry with a limit on attempts](#retry-transient-failures). |74| `connection_failed`, `request_timeout`, `server_error`, `internal_error` | **Cause:** A connection, timeout, or service failure prevented completion. <br /> **Solution:** Check saved work, then [retry with a limit on attempts](#retry-transient-failures). |

75| `authentication_error` | **Cause:** Model access failed because of credentials or permissions. <br /> **Solution:** Check the API key and its organization, project, and model access. |75| `authentication_error` | **Cause:** Model access failed because of credentials or permissions. <br /> **Solution:** See the shared [authentication and permission guidance](https://developers.openai.com/api/docs/guides/error-codes#python-library-error-types). |

76| `resource_not_found` | **Cause:** The requested model or resource is unavailable. <br /> **Solution:** Check the model and session configuration before retrying. |76| `resource_not_found` | **Cause:** The requested model or resource is unavailable. <br /> **Solution:** Check the model and session configuration before retrying. |

77| `sandbox_error` | **Cause:** The environment couldn't complete an operation. <br /> **Solution:** Inspect the environment error and fix its configuration or connectivity. |77| `sandbox_error` | **Cause:** The environment couldn't complete an operation. <br /> **Solution:** Inspect the environment error and fix its configuration or connectivity. |

78| `executor_version_incompatible` | **Cause:** The executor can't run this turn. <br /> **Solution:** Upgrade the executor, then retry on the same session if it hasn't failed. |78| `executor_version_incompatible` | **Cause:** The executor can't run this turn. <br /> **Solution:** Upgrade the executor, then retry on the same session if it hasn't failed. |

79| `active_turn_not_steerable` | **Cause:** The active turn can't accept more input. <br /> **Solution:** Wait for it to finish before sending another message. |79| `active_turn_not_steerable` | **Cause:** The active turn can't accept more input. <br /> **Solution:** Wait for it to finish before sending another message. |

80| `cyber_policy`, `misalignment_policy_violation` | **Cause:** Safety systems blocked the request. <br /> **Solution:** Review the request against the applicable safety requirements before submitting revised input. |80| `cyber_policy`, `misalignment_policy_violation` | **Cause:** Safety systems blocked the request. <br /> **Solution:** Review the request against the applicable safety requirements before submitting revised input. |

81 81 

82Billing errors need a billing action, not a faster retry loop. A generic

83`usage_limit_exceeded` can still occur when a more specific cause isn't available.

84 

85## Session and environment errors82## Session and environment errors

86 83 

87A failed turn doesn't always mean the session has failed. Retrieve the session to84A failed turn doesn't always mean the session has failed. Retrieve the session to

107 104 

1081. **Check the outcome.** If a session was created, retrieve it, the turn, and [saved items](https://developers.openai.com/api/docs/guides/agents-api/sessions/events#fetch-items-and-turns). If the turn is still active, keep following it. If it completed, use its result.1051. **Check the outcome.** If a session was created, retrieve it, the turn, and [saved items](https://developers.openai.com/api/docs/guides/agents-api/sessions/events#fetch-items-and-turns). If the turn is still active, keep following it. If it completed, use its result.

1092. **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.1062. **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.

1103. **Wait and limit retries.** Honor `Retry-After` when an HTTP response includes it. Otherwise, use [exponential backoff with jitter](https://developers.openai.com/api/docs/guides/rate-limits#retrying-with-exponential-backoff): increase the delay between attempts and add a small random delay. Set an attempt limit or deadline.1073. **Wait and limit retries.** Follow the shared [retry guidance](https://developers.openai.com/api/docs/guides/rate-limits#retrying-with-exponential-backoff), honoring `Retry-After` on HTTP responses and setting an attempt limit or deadline.

1114. **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](https://developers.openai.com/api/docs/guides/agents-api/sessions#continue-or-steer-the-work) asking it to continue only unfinished work. This starts a new turn with the existing conversation.1084. **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](https://developers.openai.com/api/docs/guides/agents-api/sessions#continue-or-steer-the-work) asking it to continue only unfinished work. This starts a new turn with the existing conversation.

112 109 

113Inspect tool results even when a turn completes. Stop automatic retries if the error changes or the110Inspect tool results even when a turn completes. Stop automatic retries if the error changes or the

116### Correct invalid input113### Correct invalid input

117 114 

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

116 

117For size errors, reduce the [input and output schema](https://developers.openai.com/api/docs/guides/agents-api/sessions#input-size)

118or [tool result](https://developers.openai.com/api/docs/guides/agents-api/tools/functions) before retrying.

119If the [agent configuration](https://developers.openai.com/api/docs/guides/agents-api/configuration) is too large,

120create a new session with smaller instructions and tool definitions.

121 

119For upload requirements and examples, see [Resolve upload errors](https://developers.openai.com/api/docs/guides/agents-api/environments/files#resolve-upload-errors).122For upload requirements and examples, see [Resolve upload errors](https://developers.openai.com/api/docs/guides/agents-api/environments/files#resolve-upload-errors).

120If the message identifies an image problem, check the image data or URL.123If the message identifies an image problem, check the image data or URL.

121 124 

124An `error` event or a disconnected stream doesn't confirm the turn's final state.127An `error` event or a disconnected stream doesn't confirm the turn's final state.

125Follow [Recover a disconnected stream](https://developers.openai.com/api/docs/guides/agents-api/sessions/events#how-to-recover-a-disconnected-stream)128Follow [Recover a disconnected stream](https://developers.openai.com/api/docs/guides/agents-api/sessions/events#how-to-recover-a-disconnected-stream)

126to reconnect and check saved work before resubmitting input.129to reconnect and check saved work before resubmitting input.

130If the retrieved session has `status: "failed"` or you receive `agent.session.failed`,

131stop reconnecting and follow the

132[session recovery guidance](#session-and-environment-errors).

127 133 

128If failures persist, keep the request ID, session ID, turn ID, error code, and134For [persistent errors](https://developers.openai.com/api/docs/guides/error-codes#persistent-errors), include

129time of the failure for support.135the request ID, session ID, and turn ID with your support request.

505 505 

506## How to recover a disconnected stream506## How to recover a disconnected stream

507 507 

508Streams do not replay missed events. To restore your application's view:508Recover missed output from saved items. To restore your application's view:

509 509 

5101. Open a new stream and buffer incoming events.5101. Open a new stream and buffer incoming events.

5112. Retrieve the session and its saved items while the stream stays connected.5112. Retrieve the session and its saved items while the stream stays connected.

5134. Apply buffered item updates using `item_id`. Discard updates for items that already reached their final state in the retrieved history.5134. Apply buffered item updates using `item_id`. Discard updates for items that already reached their final state in the retrieved history.

5145. Resume handling live events.5145. Resume handling live events.

515 515 

516When you reconnect to a failed session, the stream reports the saved failure and closes.

517If the retrieved session has `status: "failed"` or you receive `agent.session.failed`,

518stop reconnecting and follow the

519[session recovery guidance](https://developers.openai.com/api/docs/guides/agents-api/errors#session-and-environment-errors).

520 

516Restore pending input forms from the retrieved session's `required_actions`.521Restore pending input forms from the retrieved session's `required_actions`.

517Historical items don't indicate which requests still need a response. For522Historical items don't indicate which requests still need a response. For

518browser approvals, match forms by `request_id` and remove those no longer523browser approvals, match forms by `request_id` and remove those no longer

182 182 

183The harness continues the turn after it receives the required results. Follow [session events and items](https://developers.openai.com/api/docs/guides/agents-api/sessions/events) to check the turn's outcome and retrieve its output.183The harness continues the turn after it receives the required results. Follow [session events and items](https://developers.openai.com/api/docs/guides/agents-api/sessions/events) to check the turn's outcome and retrieve its output.

184 184 

185### Result size

186 

187If the API rejects a tool result as too large, reduce its size to less than 4 MiB (4,194,304 bytes), leaving a little room for Agents API metadata. Retry with the same `turn_id` and `call_id` while the call is still pending.

188 

185## Recover after a disconnect189## Recover after a disconnect

186 190 

187Retrieve the session to find pending actions. If you already ran a function, submit its saved result with the same `turn_id` and `call_id`.191Retrieve the session to find pending actions. If you already ran a function, submit its saved result with the same `turn_id` and `call_id`.

10 10 

11The `model` field selects the model. The `access_programs.cyber` field selects a supported access program for that request: `standard`, `daybreak_blue`, or `daybreak_red`.11The `model` field selects the model. The `access_programs.cyber` field selects a supported access program for that request: `standard`, `daybreak_blue`, or `daybreak_red`.

12 12 

13| Model | Set `model` to | Set `access_programs.cyber` to | When to use |13 

14| ---------------------------------------- | ------------------------------ | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |14 

15 

16| Model option | Model ID | Access program | When to use |

17| ---------------------------------------- | ------------------------------ | --------------- | ----------------------------------------------------------------------------------------------------------------------------- |

15| Mainline model with standard safeguards | `gpt-6-sol` | `standard` | General-purpose or security tasks with standard safeguards, even if you have Daybreak access. |18| Mainline model with standard safeguards | `gpt-6-sol` | `standard` | General-purpose or security tasks with standard safeguards, even if you have Daybreak access. |

16| Mainline model with Daybreak Blue | `gpt-6-sol` | `daybreak_blue` | Approved defensive security work with a specific mainline model. |19| Mainline model with Daybreak Blue | `gpt-6-sol` | `daybreak_blue` | Approved defensive security work with a specific mainline model. |

17| GPT-6.1 Sol or GPT-6 Astra with Daybreak | `gpt-6.1-sol` or `gpt-6-astra` | `daybreak_blue` | Reduced refusals with either model. Requires Daybreak Red approval for your organization and access enabled for your project. |20| GPT-6.1 Sol or GPT-6 Astra with Daybreak | `gpt-6.1-sol` or `gpt-6-astra` | `daybreak_blue` | Reduced refusals with either model. Requires Daybreak Red approval for your organization and access enabled for your project. |

35 35 

36## Usage tiers36## Usage tiers

37 37 

38The three paid usage tiers are **Build**, **Launch**, and **Grow**. Your organization's usage tier upgrades automatically as its total credit purchases reach each threshold. Higher tiers generally provide higher rate limits across models.38You can view the rate and usage limits for your organization under the [limits](https://platform.openai.com/settings/organization/limits) section of your account settings. As your spend on our API goes up, we automatically graduate you to the next usage tier. This usually results in an increase in rate limits across most models.

39 39 

40| Tier | Qualification | Usage limits |40| Tier | Qualification | Usage limits |

41| ------ | --------------------------------------------------------------------- | ---------------- |41| ----------- | --------------------------------------------------------------------- | ---------------- |

42| Free | User must be in an [allowed geography](https://developers.openai.com/api/docs/supported-countries) | $100 / month |42| Free | User must be in an [allowed geography](https://developers.openai.com/api/docs/supported-countries) | $100 / month |

43| Build | $5 in total credit purchases | $500 / month |43| Tier 1 | $5 paid | $100 / month |

44| Launch | $100 in total credit purchases | $5,000 / month |44| Tier 2 | $50 paid | $500 / month |

45| Grow | $500 in total credit purchases | $200,000 / month |45| Tier 3 | $100 paid | $1,000 / month |

46 46| Tier 4 | $250 paid | $5,000 / month |

47### Rate limits by usage tier47| Tier 5 | $1,000 paid | $200,000 / month |

48 

49To view the limits for each model at your usage tier, go to [Settings > Organization > Limits](https://platform.openai.com/settings/organization/limits) and review **Rate limits**. To upgrade your usage tier, select **Upgrade tier** in the **Usage Tiers** section.

50 

51| Tier | Model | RPM | TPM |

52| ------ | ----------------- | -----: | ----------: |

53| Build | Astra, Sol, Terra | 5,000 | 1,000,000 |

54| Build | Luna | 5,000 | 2,000,000 |

55| Launch | Astra, Sol, Terra | 10,000 | 4,000,000 |

56| Launch | Luna | 10,000 | 10,000,000 |

57| Grow | Astra, Sol, Terra | 15,000 | 40,000,000 |

58| Grow | Luna | 30,000 | 180,000,000 |

59 48 

60To view a high-level summary of rate limits per model, visit the [models page](https://developers.openai.com/api/docs/models).49To view a high-level summary of rate limits per model, visit the [models page](https://developers.openai.com/api/docs/models).

61 50