Error Handling

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

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);
  }
}

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
  }
}

{
  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 }
}

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}`);
    });
  }
}

client.safeGetCurrentUser()
client.safeGetCvmInfo({ id: "..." })
client.safeProvisionCvm(payload)
client.safeDeleteCvm({ id: "..." })
// etc.

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

import { PhalaCloudError, formatErrorMessage } from "@phala/cloud";

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

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

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
  }
});