Reference

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:

JSONCode
{"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 page. The ones an agent meets most:

CodeWhat to do
STALE_OBSERVATIONThe screen changed since the screenshot; nothing ran. Take a new screenshot, then act again
CONTROL_HELDA person has control in the live view; nothing ran. Wait, then take a new screenshot
OUTCOME_UNKNOWNIt may or may not have happened. Take a screenshot before trying again
SCREEN_NOT_RUNNINGThe screen is stopped or starting. Start it in the dashboard, or wait
PERMISSION_DENIEDThe token or key lacks the permission, or that screen. Grant it
ACCOUNT_PENDINGThe account waits for approval. Stop and tell the user
RATE_LIMITEDToo 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).

Limits

WhatLimit
Any tool callAnswers within 30 seconds
act1 to 20 actions per call
waitUp to 20 seconds
execThe last 8 KiB of output inline; a longer run returns an exec_id
exec_statusWaits up to 25 seconds for the command to finish
read_file, write_fileOne file up to 64 KiB, as text or base64
read_treeUp to 1,000 elements per call
ImagesOne 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, the SDK 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.