# Limits and errors (/en/docs/developers/agent/limits-and-errors)



Use this page to investigate agent configuration and session API failures. See [Embed limits and errors](/en/docs/developers/agent/embed/limits-and-errors) for tokens, origins, anonymous quotas, and components. Organization balance and quotas belong to [Usage and billing](/en/docs/developers/account/billing).

## Request and execution limits [#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 [#errors]

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 [#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 [#unauthenticated]

HTTP 401. Credentials are missing or invalid. Check the Key for this environment and organization, then authenticate again.

### SESSION\_FORBIDDEN [#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 [#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 [#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 [#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 [#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 [#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 [#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 [#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 [#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 [#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 [#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 [#diagnostics]

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](/en/docs/developers/agent/monitor), then compare your request with the [API reference](/en/docs/api/native/agent). To narrow a reproduction, start from the minimal request in the [quickstart](/en/docs/developers/agent/quickstart).