Sandbox Error Handling

Version: 0.3.0
Last Verified: 2025-01-27
Package: hopx-ai on PyPI

Overview

The Python SDK provides a comprehensive error hierarchy for handling different types of errors. All errors inherit from HopxError and provide detailed error information.

Import

from hopx_ai import (
    HopxError,
    APIError,
    AuthenticationError,
    NotFoundError,
    ValidationError,
    RateLimitError,
    ResourceLimitError,
    ServerError,
    NetworkError,
    TimeoutError,
    AgentError,
    FileNotFoundError,
    FileOperationError,
    CodeExecutionError,
    CommandExecutionError,
    DesktopNotAvailableError
)

Base Error

`HopxError`

Base exception for all HopX SDK errors. Fields:

message (str): Error message
code (str, optional): Error code
request_id (str, optional): Request ID for debugging
status_code (int, optional): HTTP status code
details (Dict[str, Any], optional): Additional error details

Example:

try:
    sandbox = Sandbox.create(template="invalid-template")
except HopxError as e:
    print(f"Error: {e.message}")
    print(f"Code: {e.code}")

Expected Output:

Error: Template not found
Code: TEMPLATE_NOT_FOUND

API Errors

`APIError`

Base class for API request failures. Inherits from: HopxError Fields:

status_code (int): HTTP status code

`AuthenticationError`

Authentication failed (401). Inherits from: APIError When raised:

Invalid or missing API key
Expired authentication token

Example:

try:
    sandbox = Sandbox.create(template="code-interpreter", api_key="invalid")
except AuthenticationError:
    print("Invalid API key")

Expected Output:

Invalid API key

`NotFoundError`

Resource not found (404). Inherits from: APIError When raised:

Sandbox not found
Template not found
File not found

Example:

try:
    sandbox = Sandbox.connect("non-existent-id")
except NotFoundError:
    print("Sandbox not found")

Expected Output:

Sandbox not found

`ValidationError`

Request validation failed (400). Inherits from: APIError Fields:

field (str, optional): Field that failed validation

When raised:

Invalid parameters
Missing required fields
Invalid data format

Example:

try:
    sandbox = Sandbox.create(template="", template_id="")
except ValidationError as e:
    print(f"Validation failed: {e.message}")
    if e.field:
        print(f"Field: {e.field}")

Expected Output:

Validation failed: Either template or template_id must be provided
Field: template

`RateLimitError`

Rate limit exceeded (429). Inherits from: APIError Fields:

retry_after (int, optional): Seconds to wait before retrying

When raised:

Too many requests in a time period

Example:

try:
    sandbox = Sandbox.create(template="code-interpreter")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after} seconds")

Expected Output:

Rate limited. Retry after 60 seconds

`ResourceLimitError`

Resource limit exceeded. Inherits from: APIError Fields:

limit (int): Resource limit
current (int): Current usage
available (int): Available resources
upgrade_url (str, optional): URL to upgrade plan

When raised:

Exceeded sandbox quota
Insufficient resources

Example:

try:
    sandbox = Sandbox.create(template="code-interpreter")
except ResourceLimitError as e:
    print(f"Limit exceeded: {e.current}/{e.limit}")
    if e.upgrade_url:
        print(f"Upgrade at: {e.upgrade_url}")

Expected Output:

Limit exceeded: 10/10
Upgrade at: https://console.hopx.dev/upgrade

`ServerError`

Server error (5xx). Inherits from: APIError When raised:

Internal server error
Service unavailable

Network Errors

`NetworkError`

Network communication failed. Inherits from: HopxError When raised:

Connection errors
DNS resolution failures

`TimeoutError`

Request timed out. Inherits from: NetworkError When raised:

Request exceeded timeout
Operation took too long

Example:

try:
    result = sandbox.run_code("import time; time.sleep(300)", timeout=60)
except TimeoutError:
    print("Execution timed out")

Expected Output:

Execution timed out

Agent Errors

`AgentError`

Base error for agent operations. Inherits from: HopxError

`FileNotFoundError`

File or directory not found in sandbox. Inherits from: AgentError Fields:

path (str): Path that was not found

Example:

try:
    content = sandbox.files.read("/nonexistent/file.txt")
except FileNotFoundError as e:
    print(f"File not found: {e.path}")

Expected Output:

File not found: /nonexistent/file.txt

`FileOperationError`

File operation failed. Inherits from: AgentError Fields:

operation (str): Operation that failed

Example:

try:
    sandbox.files.write("/readonly/file.txt", "content")
except FileOperationError as e:
    print(f"File operation failed: {e.operation}")

Expected Output:

File operation failed: write

`CodeExecutionError`

Code execution failed. Inherits from: AgentError Fields:

language (str): Language that failed

Example:

try:
    result = sandbox.run_code("invalid syntax here", language="python")
except CodeExecutionError as e:
    print(f"Code execution failed: {e.message}")

Expected Output:

Code execution failed: SyntaxError: invalid syntax

`CommandExecutionError`

Command execution failed. Inherits from: AgentError Fields:

command (str): Command that failed

Example:

try:
    result = sandbox.commands.run("nonexistent-command")
except CommandExecutionError as e:
    print(f"Command failed: {e.command}")

Expected Output:

Command failed: nonexistent-command

`DesktopNotAvailableError`

Desktop automation not available in this sandbox. Inherits from: AgentError Fields:

missing_dependencies (List[str]): Missing dependencies
docs_url (str, optional): Documentation URL
install_command (str, optional): Installation command

Example:

try:
    screenshot = sandbox.desktop.screenshot()
except DesktopNotAvailableError as e:
    print(f"Desktop not available: {e.message}")
    if e.install_command:
        print(f"Install with: {e.install_command}")

Expected Output:

Desktop not available: Desktop automation requires desktop-enabled template
Install with: Use template with desktop support

Error Handling Examples

Example 1: Basic Error Handling

from hopx_ai import Sandbox, HopxError

try:
    sandbox = Sandbox.create(template="code-interpreter")
    result = sandbox.run_code("print('Hello')")
except HopxError as e:
    print(f"Error: {e.message}")
    if hasattr(e, 'status_code'):
        print(f"Status: {e.status_code}")

Expected Output:

Hello

Example 2: Specific Error Handling

from hopx_ai import Sandbox, AuthenticationError, NotFoundError, ValidationError

try:
    sandbox = Sandbox.create(template="code-interpreter")
except AuthenticationError:
    print("Authentication failed. Check your API key.")
except NotFoundError:
    print("Template not found.")
except ValidationError as e:
    print(f"Invalid request: {e.message}")

Expected Output:

Sandbox created successfully

Example 3: Retry on Rate Limit

from hopx_ai import Sandbox, RateLimitError
import time

def create_sandbox_with_retry():
    max_retries = 3
    for attempt in range(max_retries):
        try:
            return Sandbox.create(template="code-interpreter")
        except RateLimitError as e:
            if attempt < max_retries - 1:
                wait_time = e.retry_after or 60
                print(f"Rate limited. Waiting {wait_time} seconds...")
                time.sleep(wait_time)
            else:
                raise

Expected Output:

Sandbox created successfully (after retry if needed)

Models - Data models
Sandbox - Sandbox operations that may raise errors

Next Steps

Now that you understand error handling, explore:

Error Handling Basics - Practical error handling patterns
Sandbox Operations - See errors in action
API Errors - Understand API error responses
CLI Reference - Use HopX from the command line
Troubleshooting - Common issues and solutions

Python SDK

JavaScript SDK

Overview

Import

Base Error

`HopxError`

API Errors

`APIError`

`AuthenticationError`

`NotFoundError`

`ValidationError`

`RateLimitError`

`ResourceLimitError`

`ServerError`

Network Errors

`NetworkError`

`TimeoutError`

Agent Errors

`AgentError`

`FileNotFoundError`

`FileOperationError`

`CodeExecutionError`

`CommandExecutionError`

`DesktopNotAvailableError`

Error Handling Examples

Example 1: Basic Error Handling

Example 2: Specific Error Handling

Example 3: Retry on Rate Limit

See Also

Next Steps

Python SDK

JavaScript SDK

​Overview

​Import

​Base Error

​HopxError

​API Errors

​APIError

​AuthenticationError

​NotFoundError

​ValidationError

​RateLimitError

​ResourceLimitError

​ServerError

​Network Errors

​NetworkError

​TimeoutError

​Agent Errors

​AgentError

​FileNotFoundError

​FileOperationError

​CodeExecutionError

​CommandExecutionError

​DesktopNotAvailableError

​Error Handling Examples

​Example 1: Basic Error Handling

​Example 2: Specific Error Handling

​Example 3: Retry on Rate Limit

​Related Classes

​See Also

​Next Steps

Overview

Import

Base Error

`HopxError`

API Errors

`APIError`

`AuthenticationError`

`NotFoundError`

`ValidationError`

`RateLimitError`

`ResourceLimitError`

`ServerError`

Network Errors

`NetworkError`

`TimeoutError`

Agent Errors

`AgentError`

`FileNotFoundError`

`FileOperationError`

`CodeExecutionError`

`CommandExecutionError`

`DesktopNotAvailableError`

Error Handling Examples

Example 1: Basic Error Handling

Example 2: Specific Error Handling

Example 3: Retry on Rate Limit

Related Classes

See Also

Next Steps