Skip to main content
The Hopx Python SDK provides comprehensive error handling with specific exception types for different error scenarios.

Base Exception

HopxError

Base exception for all Hopx SDK errors.
from hopx_ai.errors import HopxError

try:
    sandbox = Sandbox.create(template="invalid")
except HopxError as e:
    print(f"Error: {e.message}")
    print(f"Code: {e.code}")
    print(f"Request ID: {e.request_id}")
Properties:
  • 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, optional): Additional error details

API Errors

APIError

Base class for API-related errors.
from hopx_ai.errors import APIError

try:
    sandbox = Sandbox.create(template="code-interpreter")
except APIError as e:
    print(f"API Error: {e.message}")
    print(f"Status: {e.status_code}")

AuthenticationError

Authentication failed (401).
from hopx_ai.errors import AuthenticationError

try:
    sandbox = Sandbox.create(template="code-interpreter", api_key="invalid")
except AuthenticationError as e:
    print("Authentication failed - check your API key")

NotFoundError

Resource not found (404).
from hopx_ai.errors import NotFoundError

try:
    sandbox = Sandbox.connect("invalid-id")
except NotFoundError as e:
    print("Sandbox not found")

ValidationError

Request validation failed (400).
from hopx_ai.errors import ValidationError

try:
    sandbox = Sandbox.create()  # Missing template
except ValidationError as e:
    print(f"Validation error: {e.message}")
    print(f"Field: {e.field}")

RateLimitError

Rate limit exceeded (429).
from hopx_ai.errors import RateLimitError

try:
    # Too many requests
    for i in range(1000):
        sandbox.run_code('print("test")')
except RateLimitError as e:
    print(f"Rate limit exceeded: {e.message}")
    if e.retry_after:
        print(f"Retry after {e.retry_after}s")

ResourceLimitError

Resource limit exceeded.
from hopx_ai.errors import ResourceLimitError

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

ServerError

Server error (5xx).
from hopx_ai.errors import ServerError

try:
    sandbox = Sandbox.create(template="code-interpreter")
except ServerError as e:
    print("Server error - please try again later")

Network Errors

NetworkError

Network communication failed.
from hopx_ai.errors import NetworkError

try:
    sandbox = Sandbox.create(template="code-interpreter")
except NetworkError as e:
    print("Network error - check your connection")

TimeoutError

Request timed out.
from hopx_ai.errors import TimeoutError

try:
    result = sandbox.run_code('import time; time.sleep(100)', timeout=10)
except TimeoutError as e:
    print("Execution timed out")

Agent Operation Errors

AgentError

Base error for agent operations.
from hopx_ai.errors import AgentError

FileNotFoundError

File or directory not found in sandbox.
from hopx_ai.errors import FileNotFoundError

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

FileOperationError

File operation failed.
from hopx_ai.errors import FileOperationError

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

CodeExecutionError

Code execution failed.
from hopx_ai.errors import CodeExecutionError

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

CommandExecutionError

Command execution failed.
from hopx_ai.errors import CommandExecutionError

try:
    result = sandbox.commands.run('invalid-command-that-fails')
except CommandExecutionError as e:
    print(f"Command failed: {e.message}")
    print(f"Command: {e.command}")

DesktopNotAvailableError

Desktop automation not available in this sandbox.
from hopx_ai.errors import DesktopNotAvailableError

try:
    sandbox.desktop.click(100, 100)
except DesktopNotAvailableError as e:
    print(f"Desktop not available: {e.message}")
    print(f"Install command: {e.install_command}")
    print(f"Missing dependencies: {e.missing_dependencies}")

Error Handling Best Practices

1. Catch Specific Exceptions

from hopx_ai.errors import (
    AuthenticationError,
    NotFoundError,
    ValidationError,
    APIError
)

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

2. Check Error Properties

try:
    result = sandbox.run_code('code')
except CodeExecutionError as e:
    print(f"Error: {e.message}")
    print(f"Request ID: {e.request_id}")  # For support
    print(f"Details: {e.details}")

3. Handle Rate Limits

from hopx_ai.errors import RateLimitError
import time

try:
    result = sandbox.run_code('code')
except RateLimitError as e:
    if e.retry_after:
        print(f"Rate limited. Retry after {e.retry_after}s")
        time.sleep(e.retry_after)
        # Retry...

4. Log Request IDs

try:
    sandbox = Sandbox.create(template="code-interpreter")
except HopxError as e:
    if e.request_id:
        print(f"Request ID: {e.request_id}")  # Include in support ticket
    raise

Error Code Reference

Common error codes:
  • file_not_found: File doesn’t exist
  • file_operation_failed: File operation error
  • code_execution_failed: Code execution error
  • command_execution_failed: Command execution error
  • desktop_not_available: Desktop features not available
  • validation_error: Request validation failed
  • authentication_error: Authentication failed
  • rate_limit_exceeded: Rate limit exceeded
  • resource_limit_exceeded: Resource limit exceeded