Exceptions

Exception classes used by the Lightwheel SDK.

ApiException

class ApiException(Exception):
    def __init__(self, response: requests.Response, path: str = "")

Raised when API requests fail.

Attributes:

• message (str): Error message with path, status code, and response text

Example:

from lightwheel_sdk.loader.exception import ApiException

try:
    object_loader.acquire_by_registry(
        registry_type="objects",
        registry_name=["chair"],
        file_type="USD"
    )
except ApiException as e:
    print(f"API request failed: {e.message}")

---

AuthenticationFailedException

class AuthenticationFailedException(Exception):
    def __init__(self, message: str)

Raised when authentication fails (401).

Attributes:

• message (str): Error message

Example:

from lightwheel_sdk.loader.exception import AuthenticationFailedException

try:
    login_manager.login(username="user", password="pass")
except AuthenticationFailedException as e:
    print(f"Authentication failed: {e.message}")

---

UnknownException

class UnknownException(Exception):
    def __init__(self, message: str)

Raised for unexpected errors.

Attributes:

• message (str): Error message

Example:

from lightwheel_sdk.loader.exception import UnknownException

try:
    # SDK operation
    pass
except UnknownException as e:
    print(f"Unexpected error: {e.message}")

---

Exception Hierarchy

All SDK exceptions inherit from Python's built-in Exception class:

Exception
├── ApiException
├── AuthenticationFailedException
└── UnknownException

Error Handling Best Practices

1. Always catch specific exceptions when possible:

from lightwheel_sdk.loader.exception import (
    ApiException,
    AuthenticationFailedException
)

try:
    result = object_loader.acquire_by_registry(...)
except AuthenticationFailedException:
    # Handle authentication issues
    login_manager.login(...)
except ApiException as e:
    # Handle API errors
    print(f"API error: {e.message}")
except Exception as e:
    # Handle other unexpected errors
    print(f"Unexpected error: {e}")

2. Check error messages for debugging:

except ApiException as e:
    print(f"Status code: {e.response.status_code}")
    print(f"Response: {e.response.text}")
    print(f"Path: {e.path}")

3. Retry logic for transient failures:

import time
from lightwheel_sdk.loader.exception import ApiException

max_retries = 3
for attempt in range(max_retries):
    try:
        result = object_loader.acquire_by_registry(...)
        break
    except ApiException as e:
        if attempt < max_retries - 1:
            time.sleep(2 ** attempt)  # Exponential backoff
            continue
        raise