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