Exceptions

This document provides comprehensive documentation for all exception classes in the ViewAI Python SDK.

Overview

The ViewAI SDK provides a hierarchy of exception classes for different error scenarios:

ViewAIError: Base exception for all SDK errors
AuthenticationError: Authentication and authorization failures
APIError: API request failures
NetworkError: Network and connectivity issues
ValidationError: Data validation failures
ModelError: Model operation failures
SchemaError: Schema-related errors
DeploymentError: Model deployment failures
ConfigurationError: Configuration errors
ExportError: Model export failures
TimeoutError: Operation timeout errors

Exception Hierarchy

ViewAIError (base)
├── AuthenticationError
├── APIError
├── NetworkError
├── ValidationError
├── ModelError
├── SchemaError
├── DeploymentError
├── ConfigurationError
├── ExportError
└── TimeoutError

ViewAIError

Base exception for all ViewAI SDK errors.

Definition

class ViewAIError(Exception):
    """Base exception for all ViewAI SDK errors."""

    def __init__(self, message: str, details: dict = None):
        """
        Initialize ViewAI error.

        Args:
            message: Error message
            details: Additional error details
        """
        super().__init__(message)
        self.message = message
        self.details = details or {}

Attributes

message (str): Human-readable error message
details (dict): Additional error context and metadata

Usage

from viewai_client.exceptions import ViewAIError

try:
    # SDK operation
    client.execute_prediction(data)
except ViewAIError as e:
    print(f"ViewAI Error: {e.message}")
    print(f"Details: {e.details}")

When Raised

All ViewAI SDK exceptions inherit from ViewAIError, so catching this exception will catch all SDK-specific errors.

Example:

from viewai_client import ViewAIClient
from viewai_client.exceptions import ViewAIError

client = ViewAIClient(api_key="your-key")

try:
    result = client.execute_prediction(data, model_id="model-123")
except ViewAIError as e:
    # Handle any ViewAI SDK error
    print(f"SDK Error: {e.message}")
    if e.details:
        print(f"Error details: {e.details}")

AuthenticationError

Raised when API authentication fails.

Definition

class AuthenticationError(ViewAIError):
    """Raised when API authentication fails."""

When Raised

Invalid API key
Expired API key
Missing API key
Insufficient permissions
Token validation failure

Common Causes

Invalid API Key

# Incorrect or invalid API key
client = ViewAIClient(api_key="invalid-key")

Missing API Key

# No API key provided
client = ViewAIClient()  # Raises ValueError

Expired Credentials

API key has expired
Token needs to be refreshed

Handling

from viewai_client import ViewAIClient
from viewai_client.exceptions import AuthenticationError

try:
    client = ViewAIClient(api_key="your-key")
    workspaces = client.list_accessible_workspaces()
except AuthenticationError as e:
    print(f"Authentication failed: {e.message}")
    print("Please check your API key and try again")
    # Log user out or prompt for new credentials

Best Practices

import os
from viewai_client import ViewAIClient
from viewai_client.exceptions import AuthenticationError

# Load API key from environment
api_key = os.getenv("VIEWAI_API_KEY")

if not api_key:
    raise ValueError("VIEWAI_API_KEY environment variable not set")

try:
    client = ViewAIClient(api_key=api_key)
    # Verify authentication
    health = client.verify_api_connectivity()
    if not health.get('healthy'):
        raise AuthenticationError("Failed to authenticate with API")

except AuthenticationError as e:
    print(f"Authentication error: {e.message}")
    # Handle authentication failure (e.g., redirect to login)

APIError

Raised when API requests fail.

Definition

class APIError(ViewAIError):
    """Raised when API requests fail."""

    def __init__(self, message: str, status_code: int = None, response: dict = None):
        """
        Initialize API error.

        Args:
            message: Error message
            status_code: HTTP status code
            response: API response body
        """
        super().__init__(message, {"status_code": status_code, "response": response})
        self.status_code = status_code
        self.response = response

Attributes

message (str): Error message
status_code (int): HTTP status code (400, 404, 500, etc.)
response (dict): Full API response body

When Raised

HTTP 4xx errors (client errors)
HTTP 5xx errors (server errors)
Malformed API responses
API rate limiting
Resource not found

Common Scenarios

400 Bad Request

try:
    # Invalid data format
    result = client.execute_prediction(
        data="invalid",  # Should be dict or list
        model_id="model-123"
    )
except APIError as e:
    if e.status_code == 400:
        print(f"Bad request: {e.message}")
        print(f"Response: {e.response}")

404 Not Found

try:
    # Non-existent model
    result = client.execute_prediction(
        data={"age": 35},
        model_id="non-existent-model"
    )
except APIError as e:
    if e.status_code == 404:
        print(f"Model not found: {e.message}")

429 Rate Limited

import time
from viewai_client.exceptions import APIError

try:
    result = client.execute_prediction(data, model_id="model-123")
except APIError as e:
    if e.status_code == 429:
        # Rate limited, wait and retry
        retry_after = e.response.get('retry_after', 60)
        print(f"Rate limited, waiting {retry_after}s")
        time.sleep(retry_after)
        # Retry request

500 Server Error

try:
    result = client.execute_prediction(data, model_id="model-123")
except APIError as e:
    if e.status_code >= 500:
        print(f"Server error: {e.message}")
        # Log error and retry with backoff

Handling

from viewai_client import ViewAIClient
from viewai_client.exceptions import APIError
import time

def make_prediction_with_retry(client, data, model_id, max_retries=3):
    """Make prediction with retry logic."""
    for attempt in range(max_retries):
        try:
            return client.execute_prediction(data, model_id=model_id)

        except APIError as e:
            # Handle different status codes
            if e.status_code == 400:
                # Client error, don't retry
                print(f"Bad request: {e.message}")
                raise

            elif e.status_code == 404:
                # Not found, don't retry
                print(f"Resource not found: {e.message}")
                raise

            elif e.status_code == 429:
                # Rate limited, wait and retry
                wait_time = min(2 ** attempt, 60)
                print(f"Rate limited, waiting {wait_time}s")
                time.sleep(wait_time)

            elif e.status_code >= 500:
                # Server error, retry with backoff
                if attempt < max_retries - 1:
                    wait_time = 2 ** attempt
                    print(f"Server error, retrying in {wait_time}s")
                    time.sleep(wait_time)
                else:
                    raise

            else:
                # Unknown error
                raise

    raise APIError("Max retries exceeded", status_code=None)

NetworkError

Raised when network operations fail.

Definition

class NetworkError(ViewAIError):
    """Raised when network operations fail."""

When Raised

Connection timeout
DNS resolution failure
Network unreachable
Connection refused
SSL/TLS errors

Common Causes

Connection Timeout

from viewai_client.config import ClientConfiguration

config = ClientConfiguration(
    api_key="your-key",
    connection_timeout=1  # Very short timeout
)
client = ViewAIClient(config=config)
# May raise NetworkError if connection takes > 1s

Network Unreachable

No internet connection
Firewall blocking requests
VPN issues

DNS Failure

Invalid base URL
DNS server unavailable

Handling

from viewai_client import ViewAIClient
from viewai_client.exceptions import NetworkError
import time

def connect_with_retry(api_key, max_retries=3):
    """Connect to ViewAI with network retry logic."""
    for attempt in range(max_retries):
        try:
            client = ViewAIClient(api_key=api_key)
            # Test connection
            health = client.verify_api_connectivity()
            if health.get('healthy'):
                return client

        except NetworkError as e:
            print(f"Network error: {e.message}")
            if attempt < max_retries - 1:
                wait_time = 2 ** attempt
                print(f"Retrying in {wait_time}s...")
                time.sleep(wait_time)
            else:
                print("Network unavailable after all retries")
                raise

    raise NetworkError("Failed to establish connection")

# Use with retry
try:
    client = connect_with_retry("your-api-key")
except NetworkError as e:
    print(f"Cannot connect: {e.message}")
    # Notify user about network issues

ValidationError

Raised when data validation fails.

Definition

class ValidationError(ViewAIError):
    """Raised when data validation fails."""

When Raised

Invalid data format
Missing required fields
Type mismatch
Value out of range
Schema validation failure

Common Scenarios

Missing Fields

from viewai_client.exceptions import ValidationError

try:
    # Missing required fields
    result = client.execute_prediction(
        data={"age": 35},  # Missing other required fields
        model_id="model-123"
    )
except ValidationError as e:
    print(f"Validation error: {e.message}")
    print(f"Missing fields: {e.details.get('missing_fields')}")

Type Mismatch

try:
    # Wrong data type
    result = client.execute_prediction(
        data={"age": "thirty-five"},  # Should be int
        model_id="model-123"
    )
except ValidationError as e:
    print(f"Type error: {e.message}")

Value Out of Range

try:
    # Value exceeds valid range
    result = client.execute_prediction(
        data={"age": 200},  # Exceeds max age
        model_id="model-123"
    )
except ValidationError as e:
    print(f"Range error: {e.message}")

Handling

from viewai_client import ViewAIClient
from viewai_client.exceptions import ValidationError

def safe_prediction(client, data, model_id):
    """Make prediction with validation error handling."""
    try:
        # Validate data first if possible
        if hasattr(client.prediction_service, 'validate_prediction_data'):
            if not client.prediction_service.validate_prediction_data(data, model_id):
                raise ValidationError("Data validation failed")

        # Execute prediction
        return client.execute_prediction(data, model_id=model_id)

    except ValidationError as e:
        print(f"Validation error: {e.message}")

        # Extract specific error details
        if 'missing_fields' in e.details:
            print(f"Missing fields: {e.details['missing_fields']}")

        if 'invalid_types' in e.details:
            print(f"Invalid types: {e.details['invalid_types']}")

        if 'out_of_range' in e.details:
            print(f"Out of range: {e.details['out_of_range']}")

        # Return None or raise based on application logic
        return None

# Use safe prediction
result = safe_prediction(client, data, "model-123")
if result:
    print(f"Prediction: {result.prediction}")

ModelError

Raised when model operations fail.

Definition

class ModelError(ViewAIError):
    """Raised when model operations fail."""

When Raised

Model not found
Model not ready
Model loading failure
Inference error
Model version mismatch

Handling

from viewai_client import ViewAIClient
from viewai_client.exceptions import ModelError
import time

def wait_for_model_ready(client, model_id, timeout=300):
    """Wait for model to be ready."""
    start_time = time.time()

    while time.time() - start_time < timeout:
        try:
            # Try to get model status
            model = client.registry.get_model(model_id)

            if model and model.get('status') == 'ready':
                return True

        except ModelError as e:
            print(f"Model error: {e.message}")

        # Wait before retry
        time.sleep(10)

    raise ModelError(f"Model {model_id} not ready after {timeout}s")

try:
    # Wait for model
    wait_for_model_ready(client, "model-123")

    # Make prediction
    result = client.execute_prediction(data, model_id="model-123")

except ModelError as e:
    print(f"Model error: {e.message}")

SchemaError

Raised when schema operations fail.

Definition

class SchemaError(ViewAIError):
    """Raised when schema operations fail."""

When Raised

Invalid schema format
Schema validation failure
Schema not found
Schema version mismatch

Handling

from viewai_client.exceptions import SchemaError

try:
    # Generate schema
    model.generate_schema_from_dataframe(ml_model, df)

except SchemaError as e:
    print(f"Schema error: {e.message}")
    # Fallback to manual schema definition

DeploymentError

Raised when model deployment fails.

Definition

class DeploymentError(ViewAIError):
    """Raised when model deployment fails."""

When Raised

Upload failure
Deployment timeout
Invalid model format
Resource quota exceeded

Handling

from viewai_client.exceptions import DeploymentError

try:
    dashboard_id = model.deploy()

except DeploymentError as e:
    print(f"Deployment failed: {e.message}")

    # Check specific failure reasons
    if 'quota_exceeded' in e.details:
        print("Resource quota exceeded")
    elif 'invalid_format' in e.details:
        print("Invalid model format")
    else:
        print(f"Details: {e.details}")

ConfigurationError

Raised when configuration is invalid.

Definition

class ConfigurationError(ViewAIError):
    """Raised when configuration is invalid."""

When Raised

Invalid configuration values
Missing required configuration
Configuration validation failure

Handling

from viewai_client.config import ClientConfiguration
from viewai_client.exceptions import ConfigurationError

try:
    config = ClientConfiguration(
        api_key="your-key",
        connection_timeout=-1  # Invalid
    )
    config.validate()

except (ConfigurationError, ValueError) as e:
    print(f"Configuration error: {e}")
    # Use default configuration
    config = ClientConfiguration(api_key="your-key")

ExportError

Raised when model export fails.

Definition

class ExportError(ViewAIError):
    """Raised when model export fails."""

When Raised

ONNX conversion failure
Pickle serialization failure
Unsupported model type
Export permission denied

Handling

from viewai_client.exceptions import ExportError

try:
    model = Model(
        model=trained_model,
        df=df,
        target="target",
        schema=None,
        name="My Model",
        workspace=workspace,
        project=None,
        client=client,
        export_format="onnx"
    )
    dashboard_id = model.deploy()

except ExportError as e:
    print(f"Export failed: {e.message}")

    # Try fallback to pickle
    print("Trying pickle export...")
    model = Model(
        model=trained_model,
        df=df,
        target="target",
        schema=None,
        name="My Model",
        workspace=workspace,
        project=None,
        client=client,
        export_format="pickle"  # Fallback
    )
    dashboard_id = model.deploy()

TimeoutError

Raised when an operation times out.

Definition

class TimeoutError(ViewAIError):
    """Raised when an operation times out."""

When Raised

Connection timeout
Read timeout
Operation timeout
Job monitoring timeout

Handling

from viewai_client.exceptions import TimeoutError
from viewai_client.config import ClientConfiguration

try:
    # Configure longer timeout
    config = ClientConfiguration(
        api_key="your-key",
        connection_timeout=10,
        read_timeout=60
    )
    client = ViewAIClient(config=config)

    result = client.execute_prediction(data, model_id="model-123")

except TimeoutError as e:
    print(f"Operation timed out: {e.message}")
    # Retry with longer timeout or notify user

Complete Error Handling Example

from viewai_client import ViewAIClient
from viewai_client.exceptions import (
    ViewAIError,
    AuthenticationError,
    APIError,
    NetworkError,
    ValidationError,
    ModelError,
    TimeoutError
)
import time
import logging

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

def robust_prediction(api_key, data, model_id, max_retries=3):
    """Make prediction with comprehensive error handling."""

    for attempt in range(max_retries):
        try:
            # Initialize client
            client = ViewAIClient(api_key=api_key)

            # Execute prediction
            result = client.execute_prediction(data, model_id=model_id)

            logger.info("Prediction successful")
            return result

        except AuthenticationError as e:
            logger.error(f"Authentication failed: {e.message}")
            # Don't retry auth errors
            raise

        except ValidationError as e:
            logger.error(f"Validation failed: {e.message}")
            # Don't retry validation errors
            raise

        except NetworkError as e:
            logger.warning(f"Network error: {e.message}")
            if attempt < max_retries - 1:
                wait_time = 2 ** attempt
                logger.info(f"Retrying in {wait_time}s...")
                time.sleep(wait_time)
            else:
                logger.error("Max retries exceeded for network error")
                raise

        except TimeoutError as e:
            logger.warning(f"Timeout: {e.message}")
            if attempt < max_retries - 1:
                wait_time = 2 ** attempt
                logger.info(f"Retrying in {wait_time}s...")
                time.sleep(wait_time)
            else:
                logger.error("Max retries exceeded for timeout")
                raise

        except APIError as e:
            logger.error(f"API error: {e.message} (status: {e.status_code})")

            # Handle based on status code
            if e.status_code == 429:
                # Rate limited
                if attempt < max_retries - 1:
                    wait_time = 60
                    logger.info(f"Rate limited, waiting {wait_time}s")
                    time.sleep(wait_time)
                else:
                    raise

            elif e.status_code >= 500:
                # Server error, retry
                if attempt < max_retries - 1:
                    wait_time = 2 ** attempt
                    logger.info(f"Server error, retrying in {wait_time}s")
                    time.sleep(wait_time)
                else:
                    raise

            else:
                # Don't retry other API errors
                raise

        except ModelError as e:
            logger.error(f"Model error: {e.message}")
            # Don't retry model errors
            raise

        except ViewAIError as e:
            logger.error(f"ViewAI error: {e.message}")
            logger.error(f"Details: {e.details}")
            raise

        except Exception as e:
            logger.error(f"Unexpected error: {e}")
            raise

    raise TimeoutError("Max retries exceeded")

# Usage
try:
    result = robust_prediction(
        api_key="your-api-key",
        data={"age": 35, "income": 50000},
        model_id="model-123",
        max_retries=3
    )
    print(f"Prediction: {result}")

except AuthenticationError:
    print("Please check your API credentials")

except ValidationError:
    print("Please check your input data")

except NetworkError:
    print("Please check your network connection")

except ViewAIError as e:
    print(f"SDK error: {e.message}")

except Exception as e:
    print(f"Unexpected error: {e}")

hashtagOverview

hashtagException Hierarchy

hashtagViewAIError

hashtagDefinition

hashtagAttributes

hashtagUsage

hashtagWhen Raised

hashtagAuthenticationError

hashtagDefinition

hashtagWhen Raised

hashtagCommon Causes

hashtagInvalid API Key

hashtagMissing API Key

hashtagExpired Credentials

hashtagHandling

hashtagBest Practices

hashtagAPIError

hashtagDefinition

hashtagAttributes

hashtagWhen Raised

hashtagCommon Scenarios

hashtagHandling

hashtagNetworkError

hashtagDefinition

hashtagWhen Raised

hashtagCommon Causes

hashtagConnection Timeout

hashtagNetwork Unreachable

hashtagDNS Failure

hashtagHandling

hashtagValidationError

hashtagDefinition

hashtagWhen Raised

hashtagCommon Scenarios

hashtagHandling

hashtagModelError

hashtagDefinition

hashtagWhen Raised

hashtagHandling

hashtagSchemaError

hashtagDefinition

hashtagWhen Raised

hashtagHandling

hashtagDeploymentError

hashtagDefinition

hashtagWhen Raised

hashtagHandling

hashtagConfigurationError

hashtagDefinition

hashtagWhen Raised

hashtagHandling

hashtagExportError

hashtagDefinition

hashtagWhen Raised

hashtagHandling

hashtagTimeoutError

hashtagDefinition

hashtagWhen Raised

hashtagHandling

hashtagComplete Error Handling Example

hashtagSee Also

Overview

Exception Hierarchy

ViewAIError

Definition

Attributes

Usage

When Raised

AuthenticationError

Definition

When Raised

Common Causes

Invalid API Key

Missing API Key

Expired Credentials

Handling

Best Practices

APIError

Definition

Attributes

When Raised

Common Scenarios

Handling

NetworkError

Definition

When Raised

Common Causes

Connection Timeout

Network Unreachable

DNS Failure

Handling

ValidationError

Definition

When Raised

Common Scenarios

Handling

ModelError

Definition

When Raised

Handling

SchemaError

Definition

When Raised

Handling

DeploymentError

Definition

When Raised

Handling

ConfigurationError

Definition

When Raised

Handling

ExportError

Definition

When Raised

Handling

TimeoutError

Definition

When Raised

Handling

Complete Error Handling Example

See Also