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

# Exceptions

> Reference for custom exceptions raised by the Lume Python SDK.

The Lume SDK uses a hierarchy of custom exceptions to allow for fine-grained error handling. All SDK-specific exceptions inherit from a base `LumeError`.

## Exception Hierarchy

```mermaid theme={null}
graph TD
    A["LumeError"] --> B["ApiError"]
    A["LumeError"] --> C["RunError"]
    B --> D["AuthenticationError"]
    B --> E["InvalidRequestError"]
    C --> F["RunFailedError"]
    C --> G["RunTimeoutError"]
```

***

## Base Exception

### LumeError

<Card title="LumeError" icon="bug">
  The base exception class for all errors raised by the Lume SDK. Catching this exception will handle any error originating from the SDK.
</Card>

***

## API Errors

These errors occur when there is an issue with the request sent to the Lume API, typically during calls to `lume.init()` or `lume.run()`.

### ApiError

<Card title="ApiError" icon="wifi-off">
  A generic error related to communicating with the Lume API. This can be caused by network issues or unexpected server responses. Inherits from `LumeError`.
</Card>

### AuthenticationError

<Card title="AuthenticationError" icon="key">
  Raised when the provided API key is invalid, expired, or missing. Inherits from `ApiError`.
</Card>

### InvalidRequestError

<Card title="InvalidRequestError" icon="file-pen">
  Raised when the request is malformed. This commonly occurs if the `flow_version` does not exist or if the `source_path` is invalid. Inherits from `ApiError`.
</Card>

***

## Run Errors

These errors are related to the execution of a pipeline.

### RunError

<Card title="RunError" icon="jet-fighter-up">
  A generic error related to the state or execution of a run. Inherits from `LumeError`.
</Card>

### RunFailedError

<Card title="RunFailedError" icon="shield-x">
  Raised by `run.wait()` if the run terminates in a `FAILED` or `CRASHED` state. The `run` object that raises the exception will have its final status and metadata populated.

  **Example**

  ```python theme={null}
  try:
      run.wait()
  except lume.RunFailedError as e:
      print(f"Run failed with status: {run.status}")
      print(f"Error details: {run.metadata.get('error')}")
  ```
</Card>

### RunTimeoutError

<Card title="RunTimeoutError" icon="hourglass-end">
  Raised by `run.wait()` if the specified timeout is reached before the run completes. Inherits from `RunError`.
</Card>