Error Codes

Section

All API responses include structured error information. Use the code and retryable fields for programmatic error handling.

Response Format

Error responses follow this structure:

{
  "success": false,
  "error": "Element not found: button.submit",
  "code": "ELEMENT_NOT_FOUND",
  "hint": "Verify the selector exists. Try taking a snapshot first.",
  "retryable": true   // local/bridge mode only
}

Cloud mode includes hint. Local bridge mode includes retryable. Both include code.

Recorder plans and analysis errors

GET /api/credits/recorder-plans is public and returns the recorder-allowance-v1 Free and Pro plans with a mode. Mode is preview unless the server sets METER_ANALYSIS=1; only live means allowances are enforced, and enforcement also needs durable recording storage. Free: five successful cloud analyses per account, up to 120 seconds each. Pro: $19/month, 3,600 analyzed seconds per confirmed billing period, up to 900 seconds each. Storage caps (1 GiB, 20 GiB) follow the separate storage-accounting rollout. Browser credits are separate.

GET /api/credits/recorder-usage requires authentication and is private, no-store. It returns contract, mode, plan, unit, limit, used, reserved, remaining, maxAnalyzedSeconds, periodStart and resetsAt. Free counts analyses with null period fields; Pro counts seconds. remaining already subtracts in-progress reservations.

Analysis errors return success: false, status, code, error, jobId and optional limit and mode. Duration codes have status: "failed"; the others have status: "waiting". There is no retryable field, so treat the guidance below as advisory. The usage endpoint's 503 has only success, code and error. Successful upload completion returns HTTP 200 with success: true; inspect optional analysisWaiting.code for held analysis and preserve the uploaded recording.

Code	HTTP	Recovery
`RECORDER_DURATION_UNKNOWN`	422	Do not resubmit the same media; its duration could not be verified.
`RECORDER_DURATION_LIMIT`	422	Use a shorter recording or a plan with a longer per-recording limit.
`RECORDER_ALLOWANCE_EXHAUSTED`	402	Free: upgrade. Pro: wait for the next confirmed billing period. Browser-credit top-ups do not restore it.
`RECORDER_RESERVATION_LIMIT`	409	Wait for an in-progress analysis to finish, then retry.
`RECORDER_ENTITLEMENT_UNAVAILABLE`	503	Retry later; plan or allowance state could not be verified.

Cloud API Error Codes

Source: error-handler.ts — shared by cloud session and recording routes

Storage accounting remains disabled pending release acceptance. Check recording state before retrying an uncertain upload.

Code	HTTP	Retry	Meaning	Hint
`ELEMENT_NOT_FOUND`	404	YES	CSS selector matched nothing	Take a snapshot to inspect the DOM
`ELEMENT_IN_IFRAME`	404	YES	Element is inside an iframe	Use a frame-aware selector
`ELEMENT_IN_SHADOW_DOM`	404	YES	Element is inside a shadow DOM	Use >>> shadow-piercing syntax
`NAVIGATION_TIMEOUT`	504	YES	Page took too long to load	Increase timeout or check URL
`OPERATION_TIMEOUT`	504	YES	Operation exceeded time limit	Simplify the operation or increase timeout
`SESSION_CLOSED`	410	FATAL	Browser session was closed	Create a new session
`PAGE_NAVIGATED`	409	YES	Navigation occurred during operation	Wait for navigation, then retry
`BROWSER_PROTOCOL_ERROR`	502	YES	Browser internal communication error	Retry or create new session
`STORAGE_TIMEOUT`	503	YES	Storage backend slow or unreachable	Retry in a few seconds
`STORAGE_ERROR`	502	YES	Storage backend returned an error	Usually transient, retry
`BROWSER_POOL_UNAVAILABLE`	503	YES	No browser instances available	Retry in 10-30 seconds
`SESSION_LIMIT_REACHED`	429	YES	Maximum concurrent sessions reached	Delete unused sessions first (DELETE /api/sessions/:id), or wait up to 30 min for idle sessions to auto-expire, then retry
`PROVISIONING_FAILED`	503	YES	Cloud machine provisioning failed	Retry in 30 seconds
`AUTH_SERVICE_UNAVAILABLE`	503	YES	API-key validation storage is temporarily unavailable	Retry in a few seconds; your API key was not rejected
`INVALID_API_KEY`	401	NO	API key invalid or expired	Check or regenerate your API key
`EVALUATE_FAILED`	400	FATAL	JavaScript evaluation error	Check script for syntax errors
`PAYLOAD_TOO_LARGE`	413	NO	Request body exceeds size limit	Reduce payload size
`INSUFFICIENT_CREDITS`	402	FATAL	Not enough credits for this operation	Purchase credits at /api/credits/checkout
`WS_DISCONNECTED`	503	YES	Chrome extension WebSocket disconnected	Ensure the extension is running and connected
`CLI_TIMEOUT`	504	YES	Server-side CLI agent timed out	Try a simpler task or increase timeout
`CLI_FAILED`	502	YES	Server-side CLI agent process error	Check server logs; agent exited non-zero
`NETWORK_ERROR`	502	YES	Target URL unreachable	Verify URL is correct and accessible
`STORAGE_CAP_EXCEEDED`	413	NO	Storage limit reached (storage preview)	Delete recordings to free storage or upgrade before uploading
`STORAGE_OWNER_REQUIRED`	403	NO	Recording owner could not be confirmed (storage preview)	Sign in to the recording owner account
`STORAGE_UPLOAD_DECLARATION_REQUIRED`	400	NO	Upload length or checksum is invalid (storage preview)	Correct the upload declaration before retrying
`STORAGE_ACCOUNTING_UNAVAILABLE`	503	NO	Storage accounting could not confirm the upload (storage preview)	Read current recording state; do not automatically resubmit
`STORAGE_PROVIDER_IDENTITY_MISMATCH`	503	NO	Provider identity could not be confirmed (storage preview)	Read current recording state; do not automatically resubmit
`STORAGE_ACCOUNTING_CONFLICT`	409	NO	Recording storage state changed (storage preview)	Refresh the recording and resolve pending uploads before retrying
`RECORDING_OWNERSHIP_DENIED`	409	NO	Recording ownership changed or could not be confirmed	Refresh the recording and confirm ownership before trying again
`RECORDING_MUTATION_UNCERTAIN`	503	NO	Recording update outcome could not be confirmed	Read current recording state before retrying; never automatically resubmit
`RECORDING_GUARDED_READ_FAILED`	503	YES	Storage preimage read failed; no update submitted	Retry after storage recovers and confirm current recording state
`RECORDING_STORAGE_UNAVAILABLE`	503	YES	Authoritative recording metadata read is temporarily unavailable	Retry GET with bounded backoff; inspect state before retrying a write. Cached state is not served during an outage.
`ANALYSIS_SUBMISSION_RECONCILIATION_REQUIRED`	409	NO	An earlier analysis submission must resolve before analysis or video can change	Check analysis status and retry manually once the submission resolves; contact support if it persists
`INTERNAL_ERROR`	500	YES	Unclassified server error	Check server logs

Local Mode Error Codes

Source: local native host — run thinkrun attach <tabId> before issuing commands

Code	HTTP	Retry	Meaning	Hint
`EXTENSION_NOT_CONNECTED`	503	YES	Chrome extension is disconnected or still reconnecting	If the extension is not installed, open Chrome with ThinkRun. Otherwise wait briefly or run thinkrun doctor.
`EXTENSION_DISCONNECTED`	503	YES	Extension disconnected mid-request	Run thinkrun doctor first. If the bridge is healthy, use thinkrun session debug --json for continuity details.
`REQUEST_TIMEOUT`	504	YES	Native host request timed out (30s)	Retry or check extension responsiveness
`COMMAND_TIMEOUT`	504	YES	Extension command execution timed out	Simplify the action or increase timeout
`TAB_NOT_FOUND`	410	FATAL	Target tab was closed or the remembered local binding is stale	Run: thinkrun tabs, then thinkrun attach <tabId> for a live tab
`TAB_NOT_OWNED`	403	FATAL	Agent session does not own this tab	Run: thinkrun attach <tabId> to claim this tab
`TAB_OWNED_BY_OTHER_SESSION`	403	FATAL	Another local session owns the tab, or the local authority cache is stale	Run: thinkrun session debug --json first. If continuity is still yours, re-attach only to rebuild authority. If another live owner holds the tab, use thinkrun new-window or wait for release.
`SESSION_NOT_FOUND`	404	FATAL	Agent session ID not registered in native host	Run: thinkrun attach <tabId> to register a session
`ELEMENT_NOT_FOUND`	404	YES	CSS selector matched nothing	Check selector against page DOM
`NAVIGATION_FAILED`	502	YES	Page load failed (net::ERR_*)	Verify URL is accessible
`SCRIPT_ERROR`	400	FATAL	JavaScript syntax or runtime error	Fix the script
`TASK_TIMEOUT`	—	NO	AI task exceeded configured timeout	Increase --timeout or break the task into smaller steps
`BRIDGE_UNREACHABLE`	—	FATAL	Local bridge could not be reached before the attach or switch request was issued	Run: thinkrun doctor
`NATIVE_HOST_UNREACHABLE`	—	FATAL	Client-side bridge route could not be reached after port revalidation	Run: thinkrun doctor. If a mutating command was in flight, verify page state before retrying.
`NATIVE_HOST_ERROR`	—	FATAL	Native host bridge is not running or encountered a fatal error	Run: thinkrun doctor

Blank status cells on native-host bridge errors mean the CLI surfaced a structured local error before any HTTP response was produced.

Native-host self-install (thinkbrowse-host --install) returns a non-zero exit code on partial manifest-write failures so scripts can detect incomplete installs.

Fatal vs Transient Errors

The task executor uses a smart circuit breaker to distinguish fatal errors (stop immediately) from transient errors (retry with backoff). The native-host bridge has its own circuit breaker that opens after 3 consecutive non-app errors (e.g. command timeouts). If thinkrun doctor reports a circuit-breaker trip, run thinkrun reset-connection to re-arm it without reloading the extension.

Fatal (stop immediately)

2 consecutive fatal errors aborts the task.

SESSION_CLOSED — browser gone
TAB_NOT_FOUND — tab gone
TAB_NOT_OWNED — run attach
TAB_OWNED_BY_OTHER_SESSION — session debug before any re-attach
SESSION_NOT_FOUND — run attach
SCRIPT_ERROR — bad JavaScript
EVALUATE_FAILED — eval error
BRIDGE_UNREACHABLE — doctor before retrying attach, switch-tab, or focus
NATIVE_HOST_UNREACHABLE — doctor + verify page state before manually re-issuing mutating commands
NATIVE_HOST_ERROR — run doctor
INVALID_API_KEY — bad key
INSUFFICIENT_CREDITS — buy credits

Transient (retry with backoff)

5 transient errors within 60s aborts the task.

ELEMENT_NOT_FOUND — may appear during load
NAVIGATION_TIMEOUT — slow page
EXTENSION_NOT_CONNECTED — reconnecting
BROWSER_PROTOCOL_ERROR — transient
AUTH_SERVICE_UNAVAILABLE — retry; do not rotate the API key
HTTP 502, 503, 504, 524

Handling Errors Programmatically

# Check the code field in the response
RESP=$(curl -s -X POST "$BASE/api/sessions/$SID/click" \
  -H "x-api-key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"selector": ".nonexistent"}')

CODE=$(echo "$RESP" | jq -r '.code // empty')
case "$CODE" in
  SESSION_CLOSED|TAB_NOT_FOUND)
    echo "Fatal: session gone, create a new one" ;;
  TAB_NOT_OWNED|SESSION_NOT_FOUND)
    echo "Fatal: run thinkrun attach <tabId>" ;;
  TAB_OWNED_BY_OTHER_SESSION)
    echo "Inspect session debug first; same-lineage re-attach may still recover authority" ;;
  BRIDGE_UNREACHABLE|NATIVE_HOST_ERROR)
    echo "Fatal: run thinkrun doctor" ;;
  NATIVE_HOST_UNREACHABLE)
    echo "Fatal: safe reads already exhausted retries; run thinkrun doctor and verify page state before re-issuing mutating commands" ;;
  INVALID_API_KEY|INSUFFICIENT_CREDITS)
    echo "Fatal: fix credentials or buy credits" ;;
  SESSION_LIMIT_REACHED)
    echo "Delete unused sessions, then retry" ;;
  ELEMENT_NOT_FOUND|NAVIGATION_TIMEOUT)
    echo "Transient: retry after delay" ;;
  EVALUATE_FAILED|SCRIPT_ERROR)
    echo "Fatal: fix the script" ;;
esac

TAB_OWNED_BY_OTHER_SESSION is the main nuanced case in local mode: check thinkrun session debug --json first, because a same-lineage re-attach can recover local authority without taking over a foreign tab.