Errors

Error classes for handling different failure modes. All errors extend the base LLMError class.

Error Hierarchy

LLMError (base)
├── ValidationError
├── AuthError
├── RateLimitError
├── ModelError
├── ServerError
├── NetworkError
├── ParseError
└── ConcurrencyError

LLMError

Base class for all library errors.

class LLMError extends Error {
  name: 'LLMError'
  message: string
}

Example:

import { LLMError } from '@motioneffector/llm'

try {
  await client.chat(messages)
} catch (error) {
  if (error instanceof LLMError) {
    console.log('LLM-related error:', error.message)
  }
}

ValidationError

Thrown when input validation fails. Catches invalid parameters before making API requests.

class ValidationError extends LLMError {
  name: 'ValidationError'
  field?: string
}

Thrown when:

• Messages array is empty
• Message has invalid role
• Message content is not a string
• Temperature is outside 0-2 range
• API key or model is empty

Example:

import { ValidationError } from '@motioneffector/llm'

try {
  await client.chat([])
} catch (error) {
  if (error instanceof ValidationError) {
    console.log(`Invalid ${error.field}: ${error.message}`)
  }
}

AuthError

Thrown when authentication fails.

class AuthError extends LLMError {
  name: 'AuthError'
  status: number
}

Thrown when:

• API key is invalid (401)
• API key lacks permission (403)

Example:

import { AuthError } from '@motioneffector/llm'

try {
  await client.chat(messages)
} catch (error) {
  if (error instanceof AuthError) {
    console.log(`Auth failed (${error.status}): ${error.message}`)
  }
}

RateLimitError

Thrown when rate limit is exceeded.

class RateLimitError extends LLMError {
  name: 'RateLimitError'
  status: number
  retryAfter?: number
}

Notes:

• Automatic retries are attempted before this error is thrown
• retryAfter comes from the Retry-After header if provided

Example:

import { RateLimitError } from '@motioneffector/llm'

try {
  await client.chat(messages)
} catch (error) {
  if (error instanceof RateLimitError) {
    const wait = error.retryAfter ?? 60
    console.log(`Rate limited. Retry in ${wait} seconds`)
  }
}

ModelError

Thrown when the requested model is unavailable.

class ModelError extends LLMError {
  name: 'ModelError'
  status: number
}

Thrown when:

• Model doesn't exist
• Model is temporarily unavailable

Example:

import { ModelError } from '@motioneffector/llm'

try {
  await client.chat(messages)
} catch (error) {
  if (error instanceof ModelError) {
    console.log('Model unavailable:', error.message)
  }
}

ServerError

Thrown when the API server returns an error.

class ServerError extends LLMError {
  name: 'ServerError'
  status: number
}

Notes:

• Automatic retries are attempted for 5xx errors before this is thrown

Example:

import { ServerError } from '@motioneffector/llm'

try {
  await client.chat(messages)
} catch (error) {
  if (error instanceof ServerError) {
    console.log(`Server error (${error.status}): ${error.message}`)
  }
}

NetworkError

Thrown when network request fails.

class NetworkError extends LLMError {
  name: 'NetworkError'
  cause?: Error
}

Thrown when:

• Connection refused
• DNS lookup failed
• Request timeout
• Network unreachable

Example:

import { NetworkError } from '@motioneffector/llm'

try {
  await client.chat(messages)
} catch (error) {
  if (error instanceof NetworkError) {
    console.log('Network failed:', error.message)
    if (error.cause) {
      console.log('Caused by:', error.cause.message)
    }
  }
}

ParseError

Thrown when response parsing fails.

class ParseError extends LLMError {
  name: 'ParseError'
  cause?: Error
}

Thrown when:

• Response is not valid JSON
• Response missing expected fields
• Streaming chunk is malformed

Example:

import { ParseError } from '@motioneffector/llm'

try {
  await client.chat(messages)
} catch (error) {
  if (error instanceof ParseError) {
    console.log('Failed to parse response:', error.message)
  }
}

ConcurrencyError

Thrown when attempting concurrent operations on a conversation.

class ConcurrencyError extends LLMError {
  name: 'ConcurrencyError'
}

Thrown when:

• Calling send() while another send() is pending
• Calling sendStream() while a request is in progress
• Calling addMessage(), clear(), or clearAll() during a request

Example:

import { ConcurrencyError } from '@motioneffector/llm'

try {
  // Don't do this
  conversation.send('First')  // Not awaited
  await conversation.send('Second')  // Throws ConcurrencyError
} catch (error) {
  if (error instanceof ConcurrencyError) {
    console.log('Wait for the previous request to complete')
  }
}

Importing Errors

Import individual error types or the base class:

// Individual errors
import {
  LLMError,
  ValidationError,
  RateLimitError,
  AuthError,
  ModelError,
  ServerError,
  NetworkError,
  ParseError,
  ConcurrencyError
} from '@motioneffector/llm'

// Check against base class
if (error instanceof LLMError) {
  // It's one of ours
}

// Check specific types
if (error instanceof RateLimitError) {
  // Handle rate limiting
}