# Errors and limits

> What a failed tool call returns, what to do about it, and the sizes and times to plan for.

## How an error comes back

A tool that fails returns a normal MCP result marked as an error. Its text is the same error body as the API's, so an agent can read the code and what to do:

```json
{"error": {"code": "STALE_OBSERVATION", "message": "Input ran since your screenshot. Take a new screenshot first.",
  "request_id": "req_01jb7q0x9v2k8m4n6p3r", "retryable": false, "retry_after": null, "outcome": "not_applied"}}
```

Every code is on the [Errors](/errors) page. The ones an agent meets most:

| Code | What to do |
|---|---|
| `STALE_OBSERVATION` | The screen changed since the screenshot; nothing ran. Take a new screenshot, then act again |
| `CONTROL_HELD` | A person has control in the live view; nothing ran. Wait, then take a new screenshot |
| `OUTCOME_UNKNOWN` | It may or may not have happened. Take a screenshot before trying again |
| `SCREEN_NOT_RUNNING` | The screen is stopped or starting. Start it in the dashboard, or wait |
| `PERMISSION_DENIED` | The token or key lacks the permission, or that screen. Grant it |
| `ACCOUNT_PENDING` | The account waits for approval. Stop and tell the user |
| `RATE_LIMITED` | Too many calls. Wait `retry_after` seconds |

A call with no token, or an expired one, answers `401` and the app signs in again. A token without the permission a tool needs answers `403` with `insufficient_scope` ([Sign-in and permissions](/mcp/sign-in#when-the-app-needs-more)).

## Limits

| What | Limit |
|---|---|
| Any tool call | Answers within 30 seconds |
| `act` | 1 to 20 actions per call |
| `wait` | Up to 20 seconds |
| `exec` | The last 8 KiB of output inline; a longer run returns an `exec_id` |
| `exec_status` | Waits up to 25 seconds for the command to finish |
| `read_file`, `write_file` | One file up to 64 KiB, as text or base64 |
| `read_tree` | Up to 1,000 elements per call |
| Images | One per result, WebP under 105,000 bytes |

- **30 seconds** keeps every call inside the 60-second limit some agent apps set. Longer work goes through `exec` and `exec_status`.
- **One image per result, under 105,000 bytes,** keeps results inside claude.ai's size limit. Use `zoom` to read small text at full resolution.
- **Bigger files** go through the [API](/api), the [SDK](/sdk/typescript) or `exec` (for example `curl` on the screen).
- **Input is queued per screen,** so two agents on one screen never type into each other; a person taking control stops both.

Plan-wide limits, such as how many screens and calls per minute: [Limits](/reference/limits).
