​
Error Handling and Troubleshooting

The OcularAI SDK provides comprehensive error handling capabilities to help you diagnose and address issues in your applications. This guide explains the available error types and best practices for handling them effectively.

​
Error Hierarchy

All SDK errors inherit from the base OcularError class, making it easy to catch any SDK-related issue.

All errors raised by the SDK inherit from the base OcularError class, allowing you to catch all SDK-specific errors with a single exception handler:

from ocular import Ocular
from ocular.utils.errors import OcularError

try:
    ocular = Ocular(api_key="invalid_key")
    project = ocular.workspace("invalid_id").project("invalid_id")
except OcularError as e:
    print(f"An OcularAI SDK error occurred: {e}")

​
Specific Error Types

Using specific error types allows you to implement targeted error handling strategies in your application.

The SDK uses specific error types to help you handle different error scenarios appropriately:

Error TypeDescriptionCommon Causes
AuthenticationErrorIssues with authenticationInvalid API key, expired credentials
ValidationErrorInvalid parameters or inputsIncorrect ID format, missing required fields
ResourceNotFoundErrorRequested resource not foundNon-existent workspace, project, version, or export
RateLimitErrorAPI rate limits exceededToo many requests in a short period
ServerErrorServer-side errorsInternal server issues, maintenance
NetworkErrorNetwork connectivity issuesConnection problems, timeouts
TimeoutErrorRequest timeoutSlow network, large dataset downloads

​
Example: Handling Specific Error Types

You can catch specific error types to handle different error scenarios differently:

from ocular import Ocular
from ocular.utils.errors import (
    OcularError,
    AuthenticationError,
    ResourceNotFoundError,
    NetworkError,
    TimeoutError
)

try:
    # Initialize the SDK
    ocular = Ocular(api_key="your_api_key")

    # Get workspace, project, version, and export
    workspace = ocular.workspace("workspace_id")
    project = workspace.project("project_id")
    version = project.version("version_id")
    export = version.export("export_id")

    # Download the dataset
    dataset = export.download()

    print(f"Dataset downloaded to: {dataset}")

except AuthenticationError as e:
    print(f"Authentication failed: {e}")
    print("Please check your API key and try again.")

except ResourceNotFoundError as e:
    print(f"Resource not found: {e}")
    print("Please verify your workspace, project, version, and export IDs.")

except (NetworkError, TimeoutError) as e:
    print(f"Network or timeout error: {e}")
    print("Please check your internet connection and try again.")

except OcularError as e:
    print(f"An OcularAI SDK error occurred: {e}")

except Exception as e:
    print(f"An unexpected error occurred: {e}")

​
Retry Mechanism

For operations that might be affected by transient network issues, configuring proper retry settings can significantly improve reliability.

The SDK includes a built-in retry mechanism for transient errors like network issues or server errors. You can configure this mechanism when initializing the SDK:

from ocular import Ocular

# Configure retry behavior
ocular = Ocular(
    api_key="your_api_key",
    max_retries=5,          # Maximum number of retry attempts
    backoff_factor=1.0      # Exponential backoff factor
)

With these settings, the SDK will retry failed requests up to 5 times with exponential backoff between attempts.

​
Debug Mode

Debug mode provides detailed logs that are invaluable when troubleshooting issues with the SDK.

For troubleshooting, you can enable debug mode to get more detailed logs:

from ocular import Ocular

# Enable debug mode
ocular = Ocular(api_key="your_api_key", debug=True)

​
Common Error Scenarios and Solutions

Being familiar with these common error scenarios can save significant troubleshooting time during development.

ScenarioErrorSolution
Invalid API KeyAuthenticationErrorCheck that your API key is correct and has the necessary permissions
Incorrect Workspace/Project IDResourceNotFoundErrorVerify the IDs in the OcularAI Foundry platform
Slow DownloadsTimeoutErrorIncrease the timeout setting or use a more reliable network
”Too Many Requests” errorRateLimitErrorImplement exponential backoff, reduce request frequency
Server MaintenanceServerErrorWait and retry after some time

​
Logging and Debugging

Proper logging configuration is essential for production applications to help diagnose issues that occur in deployed environments.

When troubleshooting issues, check the SDK logs for more information:

from ocular import Ocular
from ocular.utils.logging import setup_logging

# Set up detailed logging
logger = setup_logging(level="DEBUG", format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')

# Initialize the SDK and perform operations
ocular = Ocular(api_key="your_api_key")