Error Handling

Build robust applications with Shadai's comprehensive error handling system that provides structured, actionable error information.

Automatic Error Handling

New in v0.1.30: Shadai now automatically displays clean, user-friendly error messages without requiring try-except blocks!

Clean Error Messages by Default

When an error occurs, Shadai automatically displays a formatted message instead of a verbose Python traceback:

No more verbose tracebacks! The error handler automatically:

✅ Shows the error code in brackets

✅ Displays a clear, concise message

✅ Includes actionable suggestions when available

✅ Hides internal stack traces from users

✅ Exits cleanly with appropriate error code

When to Use Manual Error Handling

You can still use try-except blocks for programmatic error handling:

Use manual error handling when:

Building UIs that need to show custom error dialogs

Implementing retry logic or fallback mechanisms

Logging errors to external services

Need programmatic access to error details

Don't use manual error handling when:

Building simple CLI scripts

Prototyping or testing

Error messages are displayed directly to users

Default formatting is sufficient

Overview

Shadai uses a hierarchical exception system with:

Structured error messages - Human-readable and user-friendly

Machine-readable error codes - For programmatic handling

Contextual information - Debug details and affected resources

Retry flags - Indicates if operation can be retried

Suggestions - Actionable guidance for resolution

Automatic formatting - Clean output without verbose tracebacks

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

Import Exceptions

Common Errors

Authentication Errors

Invalid API Key

Cause: API key is missing or incorrect

Solutions:

Verify API key in .env file

Regenerate API key if compromised

Ensure SHADAI_API_KEY environment variable is set

Missing Account Setup

Cause: API key valid but account not configured

Configuration Errors

Missing LLM or Embedding Model

Cause: Session or account lacks required AI models

Solutions:

Configure LLM model in session or account settings

Configure embedding model for document processing

Check that models are properly saved

Context Fields:

config_key: "llm_model" or "embedding_model"

reason: Detailed explanation

Resource Errors

Session Not Found

Cause: Session was deleted or UUID is incorrect

Solutions:

Verify session UUID is correct

Create new session if old one was deleted

List available sessions

Session Already Exists

Cause: Attempting to create duplicate session name

Solutions:

Use session_get_or_create instead of session_create

Choose a different session name

Delete existing session if intended

Validation Errors

Invalid File Type

Cause: Uploading unsupported file format

Supported Types: .pdf, .jpg, .jpeg, .png, .webp

Invalid Parameter

Cause: Parameter value out of acceptable range

Authorization & Limit Errors

Knowledge Points Limit Exceeded

Cause: Monthly knowledge points quota exhausted

Solutions:

Delete unused files to free knowledge points

Upgrade to higher plan tier

Wait for monthly reset (1st of month)

Context Fields:

plan_name: Current plan (e.g., "Free", "Pro")

current_value: Points used this month

max_allowed: Monthly quota

points_needed: Points required for operation

File Size Limit Exceeded

Cause: File exceeds plan's maximum file size

Solutions:

Split large file into smaller parts

Compress or optimize file

Upgrade to plan with larger file limits

External Service Errors

LLM Provider Error

Cause: AI provider API failure or rate limit

Solutions:

Retry after delay (exponential backoff)

Check if provider is experiencing outages

Switch to different model provider

Connection Errors

Cause: Network issues or server unreachable

Solutions:

Check internet connectivity

Verify base_url is correct

Increase timeout: Shadai(..., timeout=60)

Check firewall/proxy settings

Comprehensive Error Handling

Basic Pattern

Detailed Pattern with Specific Handlers

Retry Logic

Smart Retry with Retriable Check

Exponential Backoff with Jitter

Graceful Degradation

Feature Fallback Strategy

User-Friendly Error Messages

Production-Ready Error Handler

Logging Errors

Structured Logging with Context

Best Practices

✅ Do This

❌ Don't Do This

Testing Error Scenarios

Unit Tests with pytest

Error Monitoring

Integration with Sentry

Next Steps

Session Management - Handle session lifecycle

File Ingestion - Manage file uploads and errors

Best Practices - Production patterns

API Reference - Complete exception docs

Pro Tip: Use error.context to provide specific, actionable feedback. The backend provides rich context to help you build great UX.

Error Handling

Error Handling#

Automatic Error Handling#

Clean Error Messages by Default#

When to Use Manual Error Handling#

Overview#

Exception Hierarchy#

Import Exceptions#

Common Errors#

Authentication Errors#

Invalid API Key#

Missing Account Setup#

Configuration Errors#

Missing LLM or Embedding Model#

Resource Errors#

Session Not Found#

Session Already Exists#

Validation Errors#

Invalid File Type#

Invalid Parameter#

Authorization & Limit Errors#

Knowledge Points Limit Exceeded#

File Size Limit Exceeded#

External Service Errors#

LLM Provider Error#

Connection Errors#

Comprehensive Error Handling#

Basic Pattern#

Detailed Pattern with Specific Handlers#

Retry Logic#

Smart Retry with Retriable Check#

Exponential Backoff with Jitter#

Graceful Degradation#

Feature Fallback Strategy#

User-Friendly Error Messages#

Production-Ready Error Handler#

Logging Errors#

Structured Logging with Context#

Best Practices#

✅ Do This#

❌ Don't Do This#

Testing Error Scenarios#

Unit Tests with pytest#

Error Monitoring#

Integration with Sentry#

Next Steps#

Error Handling

Automatic Error Handling

Clean Error Messages by Default

When to Use Manual Error Handling

Overview

Exception Hierarchy

Import Exceptions

Common Errors

Authentication Errors

Invalid API Key

Missing Account Setup

Configuration Errors

Missing LLM or Embedding Model

Resource Errors

Session Not Found

Session Already Exists

Validation Errors

Invalid File Type

Invalid Parameter

Authorization & Limit Errors

Knowledge Points Limit Exceeded

File Size Limit Exceeded

External Service Errors

LLM Provider Error

Connection Errors

Comprehensive Error Handling

Basic Pattern

Detailed Pattern with Specific Handlers

Retry Logic

Smart Retry with Retriable Check

Exponential Backoff with Jitter

Graceful Degradation

Feature Fallback Strategy

User-Friendly Error Messages

Production-Ready Error Handler

Logging Errors

Structured Logging with Context

Best Practices

✅ Do This

❌ Don't Do This

Testing Error Scenarios

Unit Tests with pytest

Error Monitoring

Integration with Sentry

Next Steps