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.

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.

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

message · string

Error message with details about the failure.

error_code · string

Error code that can be used for conditional handling of different error types.

AgentNotHealthyError

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

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: pcc agent status my-agent")

Properties

message · string

Error message with details about the agent’s status.

error_code · string

Error code identifying the specific issue with the agent.

Authentication Errors

AuthError

Raised when authentication fails or token has expired.

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

message · string

Message explaining the authentication failure.

Configuration Errors

ConfigError

Raised when there are issues with configuration storage or retrieval.

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

message · string · default: "'Failed to update configuration'"

Message explaining the configuration issue.

ConfigFileError

Raised when the configuration file is malformed.

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: pcc auth login")

InvalidError

Raised when an invalid operation is attempted.

from pipecatcloud.exception import InvalidError

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