Typed error classes with codes, status codes, and retry support

Overview

The errors module provides a hierarchy of typed error classes. All toolkit errors extend ToolkitError, which includes an error code, HTTP status code, retryable flag, and optional cause.

No peer dependencies required.

Quick Start

import { ToolkitError, ValidationError, LLMError } from '@jamaalbuilds/ai-toolkit/errors';

try {
  await riskyOperation();
} catch (error) {
  if (error instanceof LLMError) {
    console.log(error.code);       // 'LLM_RATE_LIMITED'
    console.log(error.statusCode); // 429
    console.log(error.retryable);  // true
  }
}

Error Classes

ToolkitError

Base error class. All toolkit errors extend this.

class ToolkitError extends Error {
  code: string;
  statusCode: number;  // HTTP status code (default: 500)
  retryable: boolean;  // whether operation can be retried (default: false)
  cause?: Error;       // original error that caused this one
}

Specialized Errors

Error Class	Use Case
ValidationError	Invalid input, missing required fields
LLMError	AI provider failures, rate limits
AuthError	Authentication/authorization failures
CacheError	Cache read/write failures
StorageError	File upload/download failures
RateLimitError	Rate limit exceeded
ApiClientError	HTTP client errors

Each error class includes a code property for programmatic error handling:

try {
  await ai.generate(prompt);
} catch (error) {
  if (error instanceof LLMError && error.code === 'LLM_RATE_LIMITED') {
    // wait and retry
  }
}