Error Handling

The exceptions module provides a comprehensive hierarchy of exception types for handling various error conditions that can occur when using the Athena Client library.

Exception Hierarchy

All Athena Client exceptions inherit from the base AthenaError class, providing a consistent error handling interface.

Base Exception

exception AthenaError

Bases: Exception

Base class for all Athena exceptions.

Base class for all Athena exceptions. All other exceptions in the library inherit from this class.

Request and Response Errors

exception InvalidRequestError

Bases: AthenaError

Raised when the request is invalid.

Raised when the request data is invalid or malformed.

default_message: str = 'Invalid request'

exception InvalidResponseError

Bases: AthenaError

Raised when the response is invalid.

Raised when the response from the service is invalid or cannot be parsed.

default_message: str = 'Invalid response'

Authentication Errors

exception InvalidAuthError

Bases: AthenaError

Raised when the authentication is invalid.

Raised when authentication credentials are invalid or missing.

default_message: str = 'auth_token cannot be empty'

exception OAuthError

Bases: AthenaError

Raised when OAuth authentication fails.

Raised when OAuth authentication fails.

default_message: str = 'OAuth authentication failed'

exception TokenExpiredError

Bases: AthenaError

Raised when the authentication token has expired.

Raised when the authentication token has expired and needs to be refreshed.

default_message: str = 'Authentication token has expired'

exception CredentialError

Bases: AthenaError

Raised when there are issues with credential management.

Raised when there are issues with credential management or retrieval.

default_message: str = 'Credential management error'

Connection Errors

exception InvalidHostError

Bases: AthenaError

Raised when the host is invalid.

Raised when the host configuration is invalid or empty.

default_message: str = 'host cannot be empty'

Classification Errors

final exception ClassificationOutputError(correlation_id, error, message=None)

Bases: AthenaError

Raised when an individual classification output contains an error.

Raised when an individual classification output contains an error. This exception includes detailed information about the specific failure.

Parameters:

• correlation_id (str)

• error (ClassificationError)

• message (str | None)

Return type:

None

__init__(correlation_id, error, message=None)

Initialize the classification output error.

Args:

correlation_id: The correlation ID of the failed output error: The ClassificationError from the protobuf response message: Optional custom error message

Parameters:

• correlation_id (str)

• error (ClassificationError)

• message (str | None)

Return type:

None

Usage Examples

Basic Error Handling

from resolver_athena_client.client.exceptions import (
    AthenaError,
    InvalidAuthError,
    InvalidRequestError
)

try:
    async with AthenaClient(channel, options) as client:
        results = client.classify_images(image_iterator)
        async for result in results:
            # Process results
            pass
except InvalidAuthError as e:
    logger.error(f"Authentication failed: {e}")
    # Handle authentication error
except InvalidRequestError as e:
    logger.error(f"Invalid request: {e}")
    # Handle request validation error
except AthenaError as e:
    logger.error(f"Athena client error: {e}")
    # Handle any other Athena-specific error
except Exception as e:
    logger.error(f"Unexpected error: {e}")
    # Handle unexpected errors

OAuth Error Handling

from resolver_athena_client.client.exceptions import (
    OAuthError,
    TokenExpiredError,
    CredentialError
)

try:
    credential_helper = CredentialHelper(
        client_id=client_id,
        client_secret=client_secret
    )
    token = await credential_helper.get_token()
except OAuthError as e:
    logger.error(f"OAuth authentication failed: {e}")
    # Handle OAuth failure - check credentials
except TokenExpiredError as e:
    logger.error(f"Token expired: {e}")
    # Handle token expiration - will auto-refresh
except CredentialError as e:
    logger.error(f"Credential error: {e}")
    # Handle credential management issues

Classification Error Handling

from resolver_athena_client.client.exceptions import ClassificationOutputError
from resolver_athena_client.client.utils import process_classification_outputs

try:
    async for result in results:
        # Process outputs with error handling
        successful_outputs = process_classification_outputs(
            result,
            raise_on_error=False,
            log_errors=True
        )

        for output in successful_outputs:
            # Handle successful classifications
            pass

except ClassificationOutputError as e:
    logger.error(
        f"Classification failed for {e.correlation_id}: "
        f"{e.error_message} (code: {e.error_code})"
    )
    if e.error_details:
        logger.error(f"Error details: {e.error_details}")

Connection Error Handling

from resolver_athena_client.client.exceptions import InvalidHostError
import asyncio

try:
    channel = create_channel(host=host, auth_token=token)

except InvalidHostError as e:
    logger.error(f"Invalid host configuration: {e}")
    # Handle host configuration error

except ConnectionError as e:
    logger.error(f"Connection failed: {e}")
    # Handle network connection issues

except asyncio.TimeoutError as e:
    logger.error(f"Connection timeout: {e}")
    # Handle connection timeouts

Error Recovery Strategies

Retry Logic

import asyncio
from resolver_athena_client.client.exceptions import (
    AthenaError,
    TokenExpiredError,
    InvalidRequestError
)

async def classify_with_retry(client, image_iterator, max_retries=3):
    """Classify images with automatic retry logic."""
    for attempt in range(max_retries):
        try:
            results = client.classify_images(image_iterator)
            async for result in results:
                yield result
            break  # Success, exit retry loop

        except TokenExpiredError:
            # Token expired, credential helper will auto-refresh
            if attempt < max_retries - 1:
                await asyncio.sleep(1.0)
                continue
            raise

        except InvalidRequestError:
            # Don't retry on invalid requests
            raise

        except AthenaError as e:
            if attempt < max_retries - 1:
                logger.warning(f"Attempt {attempt + 1} failed: {e}")
                await asyncio.sleep(2.0 ** attempt)  # Exponential backoff
                continue
            raise

Graceful Degradation

from resolver_athena_client.client.exceptions import AthenaError

async def classify_with_fallback(client, image_iterator, fallback_handler=None):
    """Classify images with fallback handling."""
    try:
        results = client.classify_images(image_iterator)
        async for result in results:
            yield result

    except AthenaError as e:
        logger.error(f"Classification service failed: {e}")

        if fallback_handler:
            logger.info("Using fallback classification method")
            async for fallback_result in fallback_handler(image_iterator):
                yield fallback_result
        else:
            logger.error("No fallback available, propagating error")
            raise

Best Practices

1. Specific Exception Handling: Catch specific exception types rather than using broad exception handlers when possible.

2. Error Logging: Always log errors with sufficient context for debugging.

3. Retry Logic: Implement appropriate retry logic for transient errors like network issues or token expiration.

4. Graceful Degradation: Consider fallback strategies for critical applications.

5. Error Context: When re-raising exceptions, preserve the original context using raise ... from e.

6. Resource Cleanup: Use async context managers to ensure proper cleanup even when exceptions occur.

Common Error Scenarios

Authentication Issues

• Invalid credentials: Check OAUTH_CLIENT_ID and OAUTH_CLIENT_SECRET

• Token expiration: The credential helper handles this automatically

• Permission denied: Verify your credentials have the necessary permissions

Connection Problems

• Invalid host: Verify the ATHENA_HOST environment variable

• Network timeouts: Adjust timeout settings or check network connectivity

• Service unavailable: Implement retry logic with exponential backoff

Request Validation

• Invalid image data: Ensure images are in supported formats

• Missing required fields: Check that all required configuration is provided

• Invalid deployment ID: Verify the deployment exists and is accessible

See Also

• Client Interface - Main client interface and error handling patterns

• Authentication - Authentication setup and troubleshooting

• Examples - Complete examples with error handling