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

# Exceptions

> Shared error types raised by both clients.

<p className="sdk-ref-eyebrow">Errors</p>

# 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

```typescript theme={null}
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

```typescript theme={null}
class APIConnectionError extends ModusError {
  constructor(message: string)
}
```

**Extends:** `ModusError`

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

## AuthenticationError

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
class RunCancelledError extends ModusError {
  constructor(message?: string)
}
```

**Extends:** `ModusError`

The run was cancelled before it finished.

## StreamTimeoutError

```typescript theme={null}
class StreamTimeoutError extends ModusError {
  constructor(message?: string)
}
```

**Extends:** `ModusError`

The streaming connection timed out before a final result arrived.

## ValidationError

```typescript theme={null}
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).