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

1

Invalid API Key

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

2

Missing API Key

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

3

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

1

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

2

Network Unreachable

• No internet connection

• Firewall blocking requests

• VPN issues

3

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

---

See Also

• ViewAIClient - Main client class

• Configuration - Configuration options and retry strategies

• Service Classes - Service documentation