Error Codes

Complete reference for BAP error codes, recovery hints, and retry behavior.

All BAP errors follow JSON-RPC 2.0 error format with extended data providing recovery guidance for agents.

Error Response Format

{
  "code": -32012,
  "message": "Element not found",
  "data": {
    "retryable": true,
    "retryAfterMs": 500,
    "details": { "selector": { "type": "text", "value": "Submit" } },
    "recoveryHint": "Run observe() to refresh interactive elements, then retry with an updated selector"
  }
}

code · number · required

Numeric error code from the table below.

message · string · required

Human-readable error message.

data.retryable · boolean

Whether the operation can be retried.

data.retryAfterMs · number

Suggested delay before retrying (milliseconds).

data.details · object

Additional context (selector used, page ID, etc.).

data.recoveryHint · string

Actionable suggestion for the agent on how to recover from the error.

Error Code Reference

JSON-RPC Standard Errors

Code	Name	Retryable	Recovery Hint
-32700	ParseError	No	Fix the JSON syntax in the request
-32600	InvalidRequest	No	Ensure the request follows JSON-RPC 2.0 structure
-32601	MethodNotFound	No	Check the method name against the protocol spec
-32602	InvalidParams	No	Validate parameters against the method schema
-32603	InternalError	No	Report as a bug — this is an unexpected server error

Server State Errors

Code	Name	Retryable	Recovery Hint
-32000	ServerError	Yes	Generic server error — retry after a delay
-32001	NotInitialized	No	Send an initialize request before calling any other method
-32002	AlreadyInitialized	No	The connection is already initialized; proceed with commands

Browser Errors

Code	Name	Retryable	Recovery Hint
-32010	BrowserNotLaunched	No	Call browser/launch to start a browser
-32011	PageNotFound	No	Call page/list to see available pages, or page/create to open a new one
-32023	ContextNotFound	No	The browser context does not exist
-32024	ResourceLimitExceeded	No	Max pages or contexts reached — close some before creating new ones

Element Errors

Code	Name	Retryable	Recovery Hint
-32012	ElementNotFound	Yes	Run observe() to refresh interactive elements, then retry with an updated selector
-32013	ElementNotVisible	Yes	Scroll the element into view or wait for it to appear, then retry
-32014	ElementNotEnabled	Yes	Wait for the element to become enabled (e.g., form validation), then retry
-32020	SelectorAmbiguous	No	Use a more specific selector (testId, CSS with nth-child, or role with exact name)

Navigation and Action Errors

Code	Name	Retryable	Recovery Hint
-32015	NavigationFailed	Yes	Check the URL is valid and accessible, then retry
-32016	Timeout	Yes	Increase timeout or wait for the page to finish loading
-32017	TargetClosed	No	The page or context was closed — create a new one
-32021	ActionFailed	Varies	Run observe() to verify element state, then retry

Security and Approval Errors

Code	Name	Retryable	Recovery Hint
-32030	ApprovalDenied	No	The human operator denied this action
-32040	FrameNotFound	No	The target frame does not exist on this page
-32041	DomainNotAllowed	No	The domain is not in the server’s allowlist

Error Handling Patterns

Retry with Backoff

For retryable errors, use the retryAfterMs hint:

try {
  await client.click(text("Submit"));
} catch (error) {
  if (error instanceof BAPError && error.retryable) {
    await sleep(error.retryAfterMs ?? 1000);
    // Re-observe then retry
    const obs = await client.observe();
    await client.click(obs.interactiveElements[0].selector);
  }
}

Observe-Retry Pattern

The most common recovery pattern for element errors is to re-observe and retry:

try {
  await client.click(ref("@e5"));
} catch (error) {
  if (error.code === -32012) {
    // ElementNotFound
    const obs = await client.observe();
    // Find the element again using a different selector
    const target = obs.interactiveElements.find((el) => el.name === "Submit");
    if (target) await client.click(target.selector);
  }
}

Structured Error Classes

Both SDKs provide typed error classes for precise error handling:

TypeScript

import { BAPError, BAPElementNotFoundError, BAPTimeoutError } from "@browseragentprotocol/client";

try {
  await client.click(role("button", "Submit"));
} catch (error) {
  if (error instanceof BAPElementNotFoundError) {
    console.log("Recovery:", error.recoveryHint);
  } else if (error instanceof BAPTimeoutError) {
    console.log("Timed out after:", error.details?.timeout, "ms");
  }
}

Python

from browseragentprotocol import BAPError, BAPElementNotFoundError, BAPTimeoutError

try:
    await client.click(role("button", "Submit"))
except BAPElementNotFoundError as e:
    print(f"Recovery: {e.recovery_hint}")
except BAPTimeoutError as e:
    print(f"Timed out: {e.details}")
except BAPError as e:
    print(f"Error {e.code}: {e.message}")