> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hopx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandbox Error Handling

> Error classes and exception handling in the HopX JavaScript/TypeScript SDK. Handle API errors, network errors, agent errors, and validation errors gracefully. Learn about error types, error handling patterns, and best practices for robust error handling in your applications. Includes TypeScript error class reference and handling examples.

**Version:** 0.1.22\
**Last Verified:** 2025-01-27\
**Package:** `@hopx-ai/sdk` on [npm](https://www.npmjs.com/package/@hopx-ai/sdk)

## Overview

The JavaScript SDK provides a comprehensive error hierarchy for handling different types of errors. All errors inherit from `HopxError`.

## Import

```typescript theme={null}
import {
    HopxError,
    APIError,
    AuthenticationError,
    NotFoundError,
    ValidationError,
    RateLimitError,
    ResourceLimitError,
    ServerError,
    NetworkError,
    TimeoutError
} from '@hopx-ai/sdk';
```

## Base Error

### `HopxError`

Base exception for all HopX SDK errors.

**Properties:**

* `message` (`string`): Error message
* `code` (`string`, optional): Error code
* `requestId` (`string`, optional): Request ID for debugging
* `statusCode` (`number`, optional): HTTP status code
* `details` (`Record<string, any>`, optional): Additional error details

***

## API Errors

### `APIError`

Base class for API request failures.

**Inherits from:** `HopxError`

***

### `AuthenticationError`

Authentication failed (401).

**Inherits from:** `APIError`

**When thrown:**

* Invalid or missing API key
* Expired authentication token

***

### `NotFoundError`

Resource not found (404).

**Inherits from:** `APIError`

**When thrown:**

* Sandbox not found
* Template not found
* File not found

***

### `ValidationError`

Request validation failed (400).

**Inherits from:** `APIError`

**When thrown:**

* Invalid parameters
* Missing required fields

***

### `RateLimitError`

Rate limit exceeded (429).

**Inherits from:** `APIError`

**Properties:**

* `retryAfter` (`number`, optional): Seconds to wait before retrying

***

### `ResourceLimitError`

Resource limit exceeded.

**Inherits from:** `APIError`

**Properties:**

* `limit` (`number`): Resource limit
* `current` (`number`): Current usage
* `available` (`number`): Available resources

***

### `ServerError`

Server error (5xx).

**Inherits from:** `APIError`

***

## Network Errors

### `NetworkError`

Network communication failed.

**Inherits from:** `HopxError`

***

### `TimeoutError`

Request timed out.

**Inherits from:** `NetworkError`

***

## Error Handling Examples

### Example 1: Basic Error Handling

```typescript theme={null}
import { Sandbox, HopxError } from '@hopx-ai/sdk';

try {
    const sandbox = await Sandbox.create({ template: 'code-interpreter' });
    const result = await sandbox.runCode("print('Hello')");
} catch (error) {
    if (error instanceof HopxError) {
        console.error(`Error: ${error.message}`);
        if (error.statusCode) {
            console.error(`Status: ${error.statusCode}`);
        }
    }
}
```

### Example 2: Specific Error Handling

```typescript theme={null}
import { Sandbox, AuthenticationError, NotFoundError } from '@hopx-ai/sdk';

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

***

## Related Classes

* **[Types](/sdk/javascript/types)** - TypeScript type definitions
* **[Sandbox](/sdk/javascript/sandbox)** - Sandbox operations that may throw errors

## See Also

* [Types](/sdk/javascript/types) - Learn about type definitions
* [Core Concepts: Errors](/core-concepts/errors) - Learn about error handling

## Next Steps

Now that you understand error handling, explore:

* [Error Handling Basics](/cookbooks/getting-started/error-handling) - Practical error handling patterns
* [Sandbox Operations](/sdk/javascript/sandbox) - See errors in action
* [API Errors](/api/concepts/errors) - Understand API error responses
* **[CLI Reference](/cli/introduction)** - Use HopX from the command line
* [Troubleshooting](/api/concepts/troubleshooting) - Common issues and solutions