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

# Error Handling

> Error classes, safe methods, and error formatting utilities in the Phala Cloud JS SDK.

The `@phala/cloud` SDK provides a structured error hierarchy and two error handling patterns: throwing (default) and safe (result-based).

This page covers **how to catch and handle errors** in the SDK. For the full list of `ERR-xxxx` error codes (returned by both the API and the CLI), see the [Error Codes Reference](/phala-cloud/references/error-codes).

## Error Hierarchy

All API errors extend `PhalaCloudError`:

```
PhalaCloudError (base)
├── RequestError          — HTTP/network errors
├── ValidationError       — 422 validation errors (Pydantic)
├── AuthError             — 401/403 authentication errors
├── BusinessError         — 400/409 business logic errors
│   └── ResourceError     — Structured errors with ERR-xxxx codes
├── ServerError           — 500+ server errors
└── UnknownError          — Network issues, unexpected errors
```

## Catching Errors

### Using `instanceof`

```typescript theme={"system"}
import {
  PhalaCloudError,
  ValidationError,
  AuthError,
  BusinessError,
  ResourceError,
  ServerError,
} from "@phala/cloud";

try {
  await client.provisionCvm(payload);
} catch (error) {
  if (error instanceof ResourceError) {
    // Structured error with error code
    console.error(`Error [${error.errorCode}]: ${error.message}`);
    error.suggestions?.forEach((s) => console.log("Suggestion:", s));
  } else if (error instanceof ValidationError) {
    // Field-level validation errors
    error.validationErrors.forEach((e) => {
      console.error(`${e.field}: ${e.message}`);
    });
  } else if (error instanceof AuthError) {
    console.error("Authentication failed:", error.message);
  } else if (error instanceof BusinessError) {
    console.error("Business error:", error.message);
  } else if (error instanceof ServerError) {
    console.error("Server error:", error.message);
  }
}
```

### Using Discriminator Properties

Each error class has a boolean discriminator property:

```typescript theme={"system"}
try {
  await client.provisionCvm(payload);
} catch (error) {
  if (error.isValidationError) {
    // error is ValidationError
  } else if (error.isAuthError) {
    // error is AuthError
  } else if (error.isResourceError) {
    // error is ResourceError (extends BusinessError)
  } else if (error.isBusinessError) {
    // error is BusinessError
  } else if (error.isServerError) {
    // error is ServerError
  } else if (error.isUnknownError) {
    // error is UnknownError
  }
}
```

## Error Classes

### PhalaCloudError

Base class for all errors. Properties:

| Property | Type | Description |
| - | - | - |
| `message` | `string` | Error message |
| `status` | `number` | HTTP status code |
| `statusText` | `string` | HTTP status text |
| `detail` | `string \| Record<string, unknown> \| Array<{ msg: string }>` | Raw error detail from API |

### ValidationError

Thrown on HTTP 422. Contains parsed field-level validation errors from FastAPI/Pydantic.

| Property | Type | Description |
| - | - | - |
| `isValidationError` | `true` | Discriminator |
| `validationErrors` | `ValidationErrorItem[]` | Parsed validation errors |

Each `ValidationErrorItem`:

```typescript theme={"system"}
{
  field: string;    // e.g., "name", "resources.memory"
  message: string;  // e.g., "String should have at least 4 characters"
  type: string;     // e.g., "string_too_short", "greater_than_equal"
  context?: Record<string, unknown>;  // e.g., { min_length: 4 }
}
```

### AuthError

Thrown on HTTP 401 or 403.

| Property | Type | Description |
| - | - | - |
| `isAuthError` | `true` | Discriminator |

### BusinessError

Thrown on HTTP 400, 409, and other 4xx errors.

| Property | Type | Description |
| - | - | - |
| `isBusinessError` | `true` | Discriminator |

### ResourceError

Extends `BusinessError`. Thrown for structured errors with `ERR-xxxx` codes.

| Property | Type | Description |
| - | - | - |
| `isResourceError` | `true` | Discriminator |
| `errorCode` | `string` | Error code (e.g., `"ERR-01-001"`) |
| `structuredDetails` | `StructuredErrorDetail[]` | Field-level details |
| `suggestions` | `string[]` | Suggested fixes |
| `links` | `ErrorLink[]` | Links to documentation |

### ServerError

Thrown on HTTP 500+.

| Property | Type | Description |
| - | - | - |
| `isServerError` | `true` | Discriminator |

### UnknownError

Thrown for network issues or unexpected errors.

| Property | Type | Description |
| - | - | - |
| `isUnknownError` | `true` | Discriminator |

## Safe Methods

Every action has a `safe` variant that returns `SafeResult` instead of throwing:

```typescript theme={"system"}
const result = await client.safeProvisionCvm(payload);

if (result.success) {
  console.log("Created:", result.data);
} else {
  // result.error is PhalaCloudError
  if (result.error instanceof ValidationError) {
    result.error.validationErrors.forEach((e) => {
      console.error(`${e.field}: ${e.message}`);
    });
  }
}
```

All safe methods follow the naming convention `safe<ActionName>`:

```typescript theme={"system"}
client.safeGetCurrentUser()
client.safeGetCvmInfo({ id: "..." })
client.safeProvisionCvm(payload)
client.safeDeleteCvm({ id: "..." })
// etc.
```

## Formatting Utilities

### `formatValidationErrors(errors, options?)`

Format validation errors for display:

```typescript theme={"system"}
import { ValidationError, formatValidationErrors } from "@phala/cloud";

if (error instanceof ValidationError) {
  const formatted = formatValidationErrors(error.validationErrors, {
    numbered: true,
    indent: 2,
    showFields: true,
  });
  console.error(formatted);
}
// Output:
//   1. name: String should have at least 4 characters
//   2. memory: Input should be greater than or equal to 1024
```

Options:

| Option | Type | Default | Description |
| - | - | - | - |
| `numbered` | `boolean` | `true` | Number each error |
| `indent` | `number` | `2` | Indent size in spaces |
| `showFields` | `boolean` | `true` | Show field names |

### `formatErrorMessage(error, options?)`

Format any `PhalaCloudError` for display:

```typescript theme={"system"}
import { PhalaCloudError, formatErrorMessage } from "@phala/cloud";

if (error instanceof PhalaCloudError) {
  console.error(formatErrorMessage(error));
}
```

Options:

| Option | Type | Default | Description |
| - | - | - | - |
| `showFields` | `boolean` | `true` | Show field names in validation errors |
| `showType` | `boolean` | `false` | Include error class name |

### `formatStructuredError(error, options?)`

Format `ResourceError` with codes, details, suggestions, and links:

```typescript theme={"system"}
import { ResourceError, formatStructuredError } from "@phala/cloud";

if (error instanceof ResourceError) {
  console.error(formatStructuredError(error));
}
// Output:
// Error [ERR-02-001]: The requested instance type does not exist
//
// Details:
//   - Instance type 'invalid' is not recognized
//
// Suggestions:
//   - Use a valid instance type: tdx.small, tdx.medium, or tdx.large
//
// Learn more:
//   - View available instance types: https://cloud.phala.com/instances
```

Options:

| Option | Type | Default | Description |
| - | - | - | - |
| `showErrorCode` | `boolean` | `true` | Show error code in output |
| `showSuggestions` | `boolean` | `true` | Show suggestions |
| `showLinks` | `boolean` | `true` | Show documentation links |

## Event-Based Error Handling

Listen to errors globally via the client event system:

```typescript theme={"system"}
const client = createClient({ apiKey: "phak_your_api_key" });

client.on("error", (error) => {
  // Called for every API error, even when using safe methods
  if (error instanceof AuthError) {
    // Redirect to login
  }
});
```

## Related

* [SDK Overview](/phala-cloud/references/cloud-js-sdk/overview) — getting started
* [Error Codes Reference](/phala-cloud/references/error-codes) — full list of `ERR-xxxx` codes


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.