> ## 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.

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 SSE events.

* HTTP mapping:

  401 -> AuthenticationError 403 -> PermissionDeniedError 404 -> NotFoundError 409 -> ConflictError 422 -> UnprocessableError 429 -> RateLimitError 5xx -> InternalServerError

* SSE event mapping:

  \{ type: “error” } -> ModusError (raised from run/stream) \{ type: “cancelled” } -> RunCancelledError \{ type: “stream\_timeout” } -> StreamTimeoutError

### ModusError

```python
exception ModusError(message: str, *, status_code: int | None = None, request_id: str | None = None, response_headers: Mapping[str, str] | None = None, body: str | None = None, code: str | None = None)
```

Bases: `Exception`

Base class for all Modus SDK errors.

### APIConnectionError

```python
exception APIConnectionError(message: str)
```

Bases: [`ModusError`](#modus._exceptions.ModusError "modus._exceptions.ModusError")

Network-level failure (ConnectError, ReadTimeout, etc.) after all automatic retries are exhausted.

### AuthenticationError

```python
exception AuthenticationError(message: str, **kwargs: Any)
```

Bases: [`ModusError`](#modus._exceptions.ModusError "modus._exceptions.ModusError")

The API key is missing, invalid, or expired (HTTP 401).

Check that MODUS\_API\_KEY is set correctly, or pass api\_key= explicitly. Create a token at app.getmodus.com → Settings → API Tokens.

### PermissionDeniedError

```python
exception PermissionDeniedError(message: str, **kwargs: Any)
```

Bases: [`ModusError`](#modus._exceptions.ModusError "modus._exceptions.ModusError")

Raised when the API key does not have permission for the requested operation (HTTP 403).

### NotFoundError

```python
exception NotFoundError(message: str, **kwargs: Any)
```

Bases: [`ModusError`](#modus._exceptions.ModusError "modus._exceptions.ModusError")

The requested resource does not exist (HTTP 404).

### ConflictError

```python
exception ConflictError(message: str, **kwargs: Any)
```

Bases: [`ModusError`](#modus._exceptions.ModusError "modus._exceptions.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

```python
exception UnprocessableError(message: str, *, errors: Any | None = None, **kwargs: Any)
```

Bases: [`ModusError`](#modus._exceptions.ModusError "modus._exceptions.ModusError")

Request validation failed (HTTP 422). The errors attribute contains the full validation error detail.

### RateLimitError

```python
exception RateLimitError(message: str, *, retry_after: int | None = None, **kwargs: Any)
```

Bases: [`ModusError`](#modus._exceptions.ModusError "modus._exceptions.ModusError")

Rate limit exceeded (HTTP 429).

The retry\_after attribute contains the number of seconds to wait before retrying, if the server provided a Retry-After header. The SDK retries automatically — this error only surfaces after all retry attempts are exhausted.

### InternalServerError

```python
exception InternalServerError(message: str, *, status_code: int, **kwargs: Any)
```

Bases: [`ModusError`](#modus._exceptions.ModusError "modus._exceptions.ModusError")

The server encountered an internal error (HTTP 5xx). The SDK retries automatically — this error only surfaces after all retry attempts are exhausted.

### RunCancelledError

```python
exception RunCancelledError(message: str = 'Run was cancelled.')
```

Bases: [`ModusError`](#modus._exceptions.ModusError "modus._exceptions.ModusError")

Raised when a chat stream is cancelled before completing.

### StreamTimeoutError

```python
exception StreamTimeoutError(message: str = 'Stream timed out.')
```

Bases: [`ModusError`](#modus._exceptions.ModusError "modus._exceptions.ModusError")

Raised when a chat stream times out before completion.