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

Base Exception

HopxError

Base exception for all Hopx SDK errors.
import { HopxError } from '@hopx-ai/sdk';

try {
  const sandbox = await Sandbox.create({ template: 'invalid' });
} catch (error) {
  if (error instanceof HopxError) {
    console.log(`Error: ${error.message}`);
    console.log(`Code: ${error.code}`);
    console.log(`Request ID: ${error.requestId}`);
  }
}

API Errors

APIError

Base class for API-related errors.
import { APIError } from '@hopx-ai/sdk';

try {
  const sandbox = await Sandbox.create({ template: 'code-interpreter' });
} catch (error) {
  if (error instanceof APIError) {
    console.log(`API Error: ${error.message}`);
    console.log(`Status: ${error.statusCode}`);
  }
}

AuthenticationError

Authentication failed (401).
import { AuthenticationError } from '@hopx-ai/sdk';

try {
  const sandbox = await Sandbox.create({
    template: 'code-interpreter',
    apiKey: 'invalid'
  });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.log('Authentication failed - check your API key');
  }
}

NotFoundError

Resource not found (404).
import { NotFoundError } from '@hopx-ai/sdk';

try {
  const sandbox = await Sandbox.connect('invalid-id');
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log('Sandbox not found');
  }
}

RateLimitError

Rate limit exceeded (429).
import { RateLimitError } from '@hopx-ai/sdk';

try {
  // Too many requests
  for (let i = 0; i < 1000; i++) {
    await sandbox.runCode('print("test")');
  }
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log(`Rate limit exceeded: ${error.message}`);
  }
}

Agent Operation Errors

FileNotFoundError

File or directory not found in sandbox.
import { FileNotFoundError } from '@hopx-ai/sdk';

try {
  const content = await sandbox.files.read('/workspace/missing.txt');
} catch (error) {
  if (error instanceof FileNotFoundError) {
    console.log(`File not found: ${error.path}`);
  }
}

CodeExecutionError

Code execution failed.
import { CodeExecutionError } from '@hopx-ai/sdk';

try {
  const result = await sandbox.runCode('invalid python syntax here');
} catch (error) {
  if (error instanceof CodeExecutionError) {
    console.log(`Code execution failed: ${error.message}`);
    console.log(`Language: ${error.language}`);
  }
}

CommandExecutionError

Command execution failed.
import { CommandExecutionError } from '@hopx-ai/sdk';

try {
  const result = await sandbox.commands.run('invalid-command-that-fails');
} catch (error) {
  if (error instanceof CommandExecutionError) {
    console.log(`Command failed: ${error.message}`);
    console.log(`Command: ${error.command}`);
  }
}

DesktopNotAvailableError

Desktop automation not available in this sandbox.
import { DesktopNotAvailableError } from '@hopx-ai/sdk';

try {
  await sandbox.desktop.mouseClick(100, 100);
} catch (error) {
  if (error instanceof DesktopNotAvailableError) {
    console.log(`Desktop not available: ${error.message}`);
  }
}

Error Handling Best Practices

1. Catch Specific Exceptions

import {
  AuthenticationError,
  NotFoundError,
  APIError
} from '@hopx-ai/sdk';

try {
  const sandbox = await Sandbox.create({ template: 'code-interpreter' });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.log('Check your API key');
  } else if (error instanceof NotFoundError) {
    console.log('Resource not found');
  } else if (error instanceof APIError) {
    console.log(`API error: ${error.message}`);
  }
}

2. Check Error Properties

try {
  const result = await sandbox.runCode('code');
} catch (error) {
  if (error instanceof HopxError) {
    console.log(`Error: ${error.message}`);
    console.log(`Request ID: ${error.requestId}`);  // For support
  }
}