Skip to main content

Error Handling

The SDK raises specific exceptions for different failure modes. Catch them to handle errors gracefully.

Exception types​

from instavm import (
    InstaVM,
    AuthenticationError,
    SessionError,
    ExecutionError,
    NetworkError,
    RateLimitError,
    BrowserError,
    BrowserSessionError,
    BrowserInteractionError,
    BrowserTimeoutError,
    BrowserNavigationError,
    ElementNotFoundError,
    QuotaExceededError
)

Code execution errors​

try:
    vm = InstaVM('your_api_key')
    result = vm.execute("print('hello')")

except AuthenticationError:
    print("Invalid API key")

except SessionError as e:
    print(f"Session error: {e}")

except ExecutionError as e:
    print(f"Code execution failed: {e}")

except NetworkError as e:
    print(f"Network issue: {e}")

except RateLimitError as e:
    print(f"Rate limited: {e}")

Browser errors​

try:
    client = InstaVM('your_api_key')
    with client.browser.create_session() as session:
        session.navigate("https://example.com")
        session.click("button.nonexistent")

except ElementNotFoundError as e:
    print(f"Element not found: {e}")

except BrowserTimeoutError as e:
    print(f"Timed out: {e}")

except BrowserNavigationError as e:
    print(f"Navigation failed: {e}")

except QuotaExceededError as e:
    print(f"Quota exceeded: {e}")

except BrowserError as e:
    print(f"Browser error: {e}")

Exception hierarchy​

InstaVMError (base)
├── AuthenticationError
├── SessionError
├── ExecutionError
├── NetworkError
├── RateLimitError
├── QuotaExceededError
└── BrowserError
    ├── BrowserSessionError
    ├── BrowserInteractionError
    ├── BrowserTimeoutError
    ├── BrowserNavigationError
    └── ElementNotFoundError

Catching BrowserError catches all browser-related exceptions. Catching InstaVMError catches everything.

Retry pattern​

import time
from instavm import InstaVM, RateLimitError, NetworkError

def execute_with_retry(vm, code, max_retries=3):
    for attempt in range(max_retries):
        try:
            return vm.execute(code)
        except RateLimitError:
            time.sleep(2 ** attempt)
        except NetworkError:
            time.sleep(1)
    raise RuntimeError("Max retries exceeded")

Next steps​