Exceptions Reference

Complete reference for all Shadai exception types with attributes and usage examples.

Exception Hierarchy

ShadaiError (base)
├── ConnectionError
├── AuthenticationError
│   ├── InvalidAPIKeyError
│   └── MissingAccountSetupError
├── ResourceError
│   ├── ResourceNotFoundError
│   │   ├── SessionNotFoundError
│   │   ├── FileNotFoundError
│   │   └── AccountNotFoundError
│   └── ResourceAlreadyExistsError
│       └── SessionAlreadyExistsError
├── ValidationError
│   ├── InvalidFileTypeError
│   ├── InvalidParameterError
│   ├── MissingParameterError
│   ├── InvalidBase64Error
│   └── BatchSizeLimitExceededError
├── AuthorizationError
│   └── PlanLimitExceededError
│       ├── KnowledgePointsLimitExceededError
│       └── FileSizeLimitExceededError
├── ExternalServiceError
│   ├── LLMProviderError
│   ├── VectorStoreError
│   └── S3StorageError
├── ProcessingError
│   ├── FileParsingError
│   └── ChunkIngestionError
└── SystemError
    ├── ConfigurationError
    ├── DatabaseError
    ├── TimeoutError
    └── ServerError

Base Exception

ShadaiError

Base exception for all Shadai errors.

Attributes:

message (str): Human-readable error message

error_code (str): Machine-readable error code

error_type (str): Error category

context (dict): Additional debugging context

is_retriable (bool): Whether operation can be retried

suggestion (str | None): Optional user guidance

Example:

Authentication Errors

AuthenticationError

Raised when authentication fails.

Error Code: AUTHENTICATION_ERROR
Retriable: No

InvalidAPIKeyError

Raised when API key is invalid.

Error Code: INVALID_API_KEY
Retriable: No

MissingAccountSetupError

Raised when account setup is missing or incomplete.

Error Code: MISSING_ACCOUNT_SETUP
Retriable: No

Resource Errors

SessionNotFoundError

Raised when session doesn't exist.

Error Code: SESSION_NOT_FOUND
Retriable: No
Context: session_uuid, account_uuid

FileNotFoundError

Raised when file doesn't exist.

Error Code: FILE_NOT_FOUND
Retriable: No
Context: resource_id

SessionAlreadyExistsError

Raised when session name already exists.

Error Code: SESSION_ALREADY_EXISTS
Retriable: No
Context: session_name, account_uuid
Suggestion: "Use session_get_or_create..."

Validation Errors

InvalidFileTypeError

Raised when file type is not supported.

Error Code: INVALID_FILE_TYPE
Retriable: No
Context: file_extension, allowed_extensions

InvalidParameterError

Raised when parameter value is invalid.

Error Code: INVALID_PARAMETER
Retriable: No
Context: parameter_name, parameter_value, reason

MissingParameterError

Raised when required parameter is missing.

Error Code: MISSING_PARAMETER
Retriable: No
Context: parameter_name

Authorization Errors

KnowledgePointsLimitExceededError

Raised when monthly knowledge points quota is exhausted.

Error Code: PLAN_LIMIT_EXCEEDED
Retriable: No
Context: plan_name, current_value, max_allowed, points_needed

FileSizeLimitExceededError

Raised when file exceeds plan's size limit.

Error Code: PLAN_LIMIT_EXCEEDED
Retriable: No
Context: filename, current_value, max_allowed, plan_name

External Service Errors

LLMProviderError

Raised when LLM provider API fails.

Error Code: LLM_PROVIDER_ERROR
Retriable: Yes
Context: provider_name, status_code (optional)

System Errors

ConfigurationError

Raised when required configuration is missing.

Error Code: CONFIGURATION_ERROR
Retriable: No
Context: config_key, reason

ConnectionError

Raised when cannot connect to server.

Error Code: CONNECTION_ERROR
Retriable: Yes

ServerError

Raised when server encounters an error.

Error Code: SERVER_ERROR
Retriable: No
Context: status_code (optional)

Comprehensive Error Handling

Pattern 1: Specific Error Types

Pattern 2: Smart Retry Logic

Pattern 3: User-Friendly Messages

Exception Attributes Reference

All exceptions inherit these attributes from ShadaiError:

Attribute	Type	Description
`message`	str	Human-readable error message for display
`error_code`	str	Machine-readable code (e.g., "SESSION_NOT_FOUND")
`error_type`	str	Error category (validation_error, resource_error, etc.)
`context`	dict	Additional debugging information
`is_retriable`	bool	Whether operation can be retried
`suggestion`	str \| None	Optional actionable suggestion

Error Types Reference

Error Type	Description	Typical Action
`validation_error`	Invalid input or parameters	Fix input and retry
`authentication_error`	Invalid credentials	Re-authenticate
`authorization_error`	Insufficient permissions or quota	Upgrade or wait
`resource_error`	Resource not found or exists	Check resource
`external_service_error`	Third-party service failure	Retry later
`system_error`	Internal server error	Contact support

Exception Hierarchy

Base Exception

ShadaiError

Authentication Errors

AuthenticationError

InvalidAPIKeyError

MissingAccountSetupError

Resource Errors

SessionNotFoundError

FileNotFoundError

SessionAlreadyExistsError

Validation Errors

InvalidFileTypeError

InvalidParameterError

MissingParameterError

Authorization Errors

KnowledgePointsLimitExceededError

FileSizeLimitExceededError

External Service Errors

LLMProviderError

System Errors

ConfigurationError

ConnectionError

ServerError

Comprehensive Error Handling

Pattern 1: Specific Error Types

Pattern 2: Smart Retry Logic

Pattern 3: User-Friendly Messages

Exception Attributes Reference

Error Types Reference

Best Practices

✅ Do This

❌ Don't Do This

See Also

Exceptions Reference

Exception Hierarchy#

Base Exception#

ShadaiError#

Authentication Errors#

AuthenticationError#

InvalidAPIKeyError#

MissingAccountSetupError#

Resource Errors#

SessionNotFoundError#

FileNotFoundError#

SessionAlreadyExistsError#

Validation Errors#

InvalidFileTypeError#

InvalidParameterError#

MissingParameterError#

Authorization Errors#

KnowledgePointsLimitExceededError#

FileSizeLimitExceededError#

External Service Errors#

LLMProviderError#

System Errors#

ConfigurationError#

ConnectionError#

ServerError#

Comprehensive Error Handling#

Pattern 1: Specific Error Types#

Pattern 2: Smart Retry Logic#

Pattern 3: User-Friendly Messages#

Exception Attributes Reference#

Error Types Reference#

Best Practices#

✅ Do This#

❌ Don't Do This#

See Also#

Exception Hierarchy

Base Exception

ShadaiError

Authentication Errors

AuthenticationError

InvalidAPIKeyError

MissingAccountSetupError

Resource Errors

SessionNotFoundError

FileNotFoundError

SessionAlreadyExistsError

Validation Errors

InvalidFileTypeError

InvalidParameterError

MissingParameterError

Authorization Errors

KnowledgePointsLimitExceededError

FileSizeLimitExceededError

External Service Errors

LLMProviderError

System Errors

ConfigurationError

ConnectionError

ServerError

Comprehensive Error Handling

Pattern 1: Specific Error Types

Pattern 2: Smart Retry Logic

Pattern 3: User-Friendly Messages

Exception Attributes Reference

Error Types Reference

Best Practices

✅ Do This

❌ Don't Do This

See Also