> ## Documentation Index
> Fetch the complete documentation index at: https://daily-docs-pr-5482.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Handling

> Handle errors from the Pipecat Cloud Python SDK: exception types raised by deployment and session operations, and how to catch them.

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

## Base Exception Class

### Error

Base class for the SDK's exceptions, with one exception of its own:
[`ConfigFileError`](#configfileerror) subclasses `Exception` directly, so
catching `Error` will not catch it.

```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 == "PCC-AGENT-AT-CAPACITY":
        print("Agent pool at capacity. Try again later.")
    elif e.error_code == "PCC-1002":
        print("No API key provided.")
```

`Session.start()` raises this for every failure it can report — a missing
API key, an agent that doesn't exist, an agent that isn't ready, and
capacity limits — so `error_code` is how you tell them apart.

#### Properties

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

<ParamField path="error_code" type="string | None">
  The API's error code, such as `PCC-1002` or `PCC-AGENT-AT-CAPACITY`. See
  [Troubleshooting](/pipecat-cloud/fundamentals/error-codes) for what each one
  means. `None` when the failure carried no structured error body.
</ParamField>

### AgentNotHealthyError

Defined and exported by the package, but nothing in the SDK raises it. An
agent that isn't in a ready state surfaces as an
[`AgentStartError`](#agentstarterror) instead, so catch that:

```python theme={null}
try:
    response = await session.start()
except AgentStartError as e:
    print(f"Failed to start agent: {e}")
    print("Check agent status with: pipecat cloud agent status my-agent")
```

<Note>
  It appears in `pipecatcloud.__all__`, so it is importable and safe to
  reference in an `except` clause — it just won't ever match.
</Note>

## 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. Unlike every other
exception here it subclasses `Exception` rather than
[`Error`](#error), so a broad `except Error` won't catch it.

```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}")
```