Limits and errors
Request limits, error recovery, retries, and session diagnostics.
Use this page to investigate agent configuration and session API failures. See Embed limits and errors for tokens, origins, anonymous quotas, and components. Organization balance and quotas belong to Usage and billing.
Request and execution limits
| Item | Value | Unit and meaning |
|---|---|---|
Agent name | 1–256 | characters |
Instructions system | 100,000 | maximum characters |
Agent / session metadata | 16 / 64 / 512 | pairs / key characters / value characters |
Session title | 500 | maximum characters |
Initial initial_events | 50 | maximum events |
Session and event list limit | 1–100; 20 | range; default items |
Session budget | 2000 | default US cents (USD 20) |
Session time_zone | UTC | default; accepts IANA names |
| Custom tools | 32 / 16 KiB | maximum count / UTF-8 JSON bytes per input_schema |
A budget uses type: "limit", max_list_cost.currency: "USD", and a positive integer string in max_list_cost.amount, measured in US cents. null removes the ceiling. The budget controls subsequent model requests; it is not a cost forecast. String limits use JavaScript string length, so not every character occupies one unit. Tool schema size is measured in UTF-8 bytes.
Handle errors by code
Native API errors contain error.type, error.message, and request_id. Classified service failures can also include error.code and error.retryable; request parsing failures may have only a type and message. Use the actual response: equal HTTP statuses do not imply equal causes.
INVALID_PARAMS
HTTP 400. A request field, format, or unsupported option is invalid. Correct the request from the error message; unchanged retries will not help.
UNAUTHENTICATED
HTTP 401. Credentials are missing or invalid. Check the Key for this environment and organization, then authenticate again.
SESSION_FORBIDDEN
HTTP 403. The caller cannot access this session. Check its user and organization. Do not retry automatically or probe other users by changing IDs.
AGENT_NOT_FOUND
HTTP 404. The agent or version is missing or inaccessible. Use the ID from creation and verify its version.
SESSION_NOT_FOUND
HTTP 404. The session is missing or inaccessible. Check the returned ID and caller identity; repeating a creation request is not recovery.
MODEL_NOT_ALLOWED
HTTP 400. The model is not allowed by the pinned version. Select an allowed model or update the configuration and create a new session.
SESSION_CONFLICT
HTTP 409. The session state conflicts with the operation. Read the session or pending tool before submitting again; do not resubmit a completed tool result.
SESSION_ARCHIVED
HTTP 409. The session is archived and cannot accept messages. Retain its history for inspection and create a new session for another conversation.
INVALID_STATE
HTTP 409. The state does not permit this operation, such as deleting a running session. Interrupt it or wait for idle or termination, then check the state again.
INVALID_PAGE_TOKEN
HTTP 400. The cursor is invalid or mismatched to the query. Restart at the first page, then pass next_page unchanged with the same filters.
UPSTREAM_UNAVAILABLE
HTTP 502. An upstream is temporarily unavailable. Retry after backing off; check existing results first when creating resources or sending messages.
SANDBOX_UNAVAILABLE
HTTP 503. The execution environment is temporarily unavailable. Retry after backing off. Record the request identifier and contact support if failures persist.
When to retry
Resolve the cause first when error.retryable is false. For HTTP 429, read Retry-After and avoid tight retry loops. Temporary upstream or environment failures can be retried after backing off. A broken network connection does not prove the request was never executed. Check known sessions and events before repeating creation or message requests.
After an event stream starts, execution failures can arrive as events. A successful connection status does not establish task success. Inspect replies, pending tool confirmations, and session status; accepting a message is separate from completing its task.
Capture diagnostic information
Record the time, environment, agent and session IDs, HTTP status, error type and code, and X-Request-Id. If only request-id or request_id is available, record that value too. Keep Keys, embed tokens, and visitor credentials out of diagnostic records.
Inspect sessions and usage, then compare your request with the API reference. To narrow a reproduction, start from the minimal request in the quickstart.