Errors

Exceptions

Shared error types raised by both clients. Modus SDK exception hierarchy. All exceptions raised by the SDK are subclasses of ModusError. HTTP errors are mapped from status codes; run errors are raised from stream events.

Status / event	Error
Network failure after retries	`APIConnectionError`
HTTP 401	`AuthenticationError`
HTTP 403	`PermissionDeniedError`
HTTP 404	`NotFoundError`
HTTP 409	`ConflictError`
HTTP 422	`UnprocessableError`
HTTP 429	`RateLimitError`
HTTP 5xx	`InternalServerError`
Stream `cancelled`	`RunCancelledError`
Stream `stream_timeout`	`StreamTimeoutError`
Client-side validation	`ValidationError`

ModusError

class ModusError extends Error {
  constructor(
    message: string,
    options?: { statusCode?: number; requestId?: string; responseHeaders?: Record<string, string>; body?: string; code?: string }
  )
}

Extends: Error Base class for all Modus SDK errors. HTTP failures map to subclasses by status code. Streaming run failures map from event types (error, cancelled, stream_timeout). Properties:

statusCode: number
requestId: string
responseHeaders: Record<string, string>
body: string
code: string

APIConnectionError

class APIConnectionError extends ModusError {
  constructor(message: string)
}

Extends: ModusError Network-level failure (connection error, read timeout, etc.) after all automatic retries are exhausted.

AuthenticationError

class AuthenticationError extends ModusError {
  constructor(
    message: string,
    options?: { statusCode?: number; requestId?: string; responseHeaders?: Record<string, string>; body?: string; code?: string }
  )
}

Extends: ModusError The API key is missing, invalid, or expired (HTTP 401). Check that MODUS_API_KEY is set correctly, or pass apiKey explicitly. Create a token at app.getmodus.com → Settings → API Tokens.

PermissionDeniedError

class PermissionDeniedError extends ModusError {
  constructor(
    message: string,
    options?: { statusCode?: number; requestId?: string; responseHeaders?: Record<string, string>; body?: string; code?: string }
  )
}

Extends: ModusError The API key does not have permission for the requested operation (HTTP 403).

NotFoundError

class NotFoundError extends ModusError {
  constructor(
    message: string,
    options?: { statusCode?: number; requestId?: string; responseHeaders?: Record<string, string>; body?: string; code?: string }
  )
}

Extends: ModusError The requested resource does not exist (HTTP 404).

ConflictError

class ConflictError extends ModusError {
  constructor(
    message: string,
    options?: { statusCode?: number; requestId?: string; responseHeaders?: Record<string, string>; body?: string; code?: string }
  )
}

Extends: ModusError Idempotency conflict — a run with this ID already exists with a different body (HTTP 409). Use a new idempotency key or omit it to auto-generate.

UnprocessableError

class UnprocessableError extends ModusError {
  constructor(
    message: string,
    options?: unknown
  )
}

Extends: ModusError Request validation failed (HTTP 422). Inspect errors when present for field-level details. Properties:

errors: unknown

RateLimitError

class RateLimitError extends ModusError {
  constructor(
    message: string,
    options?: unknown
  )
}

Extends: ModusError Too many requests (HTTP 429). When present, retryAfter is the suggested wait in seconds. Properties:

retryAfter: number

InternalServerError

class InternalServerError extends ModusError {
  constructor(
    message: string,
    statusCode: number,
    options?: { statusCode?: number; requestId?: string; responseHeaders?: Record<string, string>; body?: string; code?: string }
  )
}

Extends: ModusError Unexpected server failure (HTTP 5xx).

RunCancelledError

class RunCancelledError extends ModusError {
  constructor(message?: string)
}

Extends: ModusError The run was cancelled before it finished.

StreamTimeoutError

class StreamTimeoutError extends ModusError {
  constructor(message?: string)
}

Extends: ModusError The streaming connection timed out before a final result arrived.

ValidationError

class ValidationError extends ModusError {
  constructor(message: string)
}

Extends: ModusError Client-side argument validation failed before a request was sent (for example an unsupported chat model id).

Types

Errors

Modus Classes

Modus.scopes Classes

Modus.scopes.conversations Classes

Modus.context Classes

Modus.workflows Classes

Modus.connections Classes

Modus.chat Classes

Modus.suggestions Classes

Modus.errors Classes

Management Classes

Management.scopes Classes

Management.context Classes

Management.workflows Classes

Management.tools Classes

Management.usage Classes

Management.users Classes

types Classes

types Interfaces

types Type Aliases

Exceptions

Exceptions

ModusError

APIConnectionError

AuthenticationError

PermissionDeniedError

NotFoundError

ConflictError

UnprocessableError

RateLimitError

InternalServerError

RunCancelledError

StreamTimeoutError

ValidationError

​Exceptions

​ModusError

​APIConnectionError

​AuthenticationError

​PermissionDeniedError

​NotFoundError

​ConflictError

​UnprocessableError

​RateLimitError

​InternalServerError

​RunCancelledError

​StreamTimeoutError

​ValidationError

Exceptions

ModusError

APIConnectionError

AuthenticationError

PermissionDeniedError

NotFoundError

ConflictError

UnprocessableError

RateLimitError

InternalServerError

RunCancelledError

StreamTimeoutError

ValidationError