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

# Error Handling

> Managing errors with the Pipecat Cloud Python SDK

The Pipecat Cloud SDK defines several exception classes to help you handle different error conditions.

## Base Exception Class

### Error

Base class for all Pipecat Cloud exceptions.

```python theme={null}
from pipecatcloud.exception import Error

try:
    # SDK operation
except Error as e:
    print(f"A Pipecat Cloud error occurred: {e}")
```

## Session Errors

### AgentStartError

Raised when an agent fails to start.

```python theme={null}
from pipecatcloud.exception import AgentStartError

try:
    response = await session.start()
except AgentStartError as e:
    print(f"Failed to start agent: {e}")
    if e.error_code == "429":
        print("Agent pool at capacity. Try again later.")
    elif e.error_code == "404":
        print("Agent not found.")
```

#### Properties

<ParamField path="message" type="string">
  Error message with details about the failure.
</ParamField>

<ParamField path="error_code" type="string">
  Error code that can be used for conditional handling of different error types.
</ParamField>

### AgentNotHealthyError

Raised when attempting to interact with an agent that is not in a ready state.

```python theme={null}
from pipecatcloud.exception import AgentNotHealthyError

try:
    response = await session.start()
except AgentNotHealthyError as e:
    print(f"Agent is not ready: {e}")
    print("Check agent status with: pipecat cloud agent status my-agent")
```

#### Properties

<ParamField path="message" type="string">
  Error message with details about the agent's status.
</ParamField>

<ParamField path="error_code" type="string">
  Error code identifying the specific issue with the agent.
</ParamField>

## Authentication Errors

### AuthError

Raised when authentication fails or token has expired.

```python theme={null}
from pipecatcloud.exception import AuthError

try:
    # Operation requiring authentication
except AuthError:
    print("Your session has expired. Please log in again.")
    # Prompt user to reauthenticate
```

#### Properties

<ParamField path="message" type="string" default="'Unauthorized / token expired. Please run `pipecat cloud auth login` to login again.'">
  Message explaining the authentication failure.
</ParamField>

## Configuration Errors

### ConfigError

Raised when there are issues with configuration storage or retrieval.

```python theme={null}
from pipecatcloud.exception import ConfigError

try:
    # Operation requiring config
except ConfigError as e:
    print(f"Configuration error: {e.message}")
    # Guide user to fix configuration
```

#### Properties

<ParamField path="message" type="string" default="'Failed to update configuration'">
  Message explaining the configuration issue.
</ParamField>

### ConfigFileError

Raised when the configuration file is malformed.

```python theme={null}
from pipecatcloud.exception import ConfigFileError

try:
    # Operation requiring config file
except ConfigFileError:
    print("Your configuration file is invalid or corrupted.")
    print("Try recreating it with: pipecat cloud auth login")
```

### InvalidError

Raised when an invalid operation is attempted.

```python theme={null}
from pipecatcloud.exception import InvalidError

try:
    # Potentially invalid operation
except InvalidError as e:
    print(f"Invalid operation: {e}")
```