Aıon

Documentation

Troubleshooting

Common issues and solutions when using the AionVision SDK

Need Help?

If you can't find a solution here, reach out to support@aionvision.tech or check the FAQ.

Authentication Errors

Error: AuthenticationError: Authentication failed

Solutions:

  • Verify your API key is correct and not expired
  • Check that the API key has the required permissions
  • Ensure no extra whitespace in the API key
# Verify your API key
import os
api_key = os.getenv("AIONVISION_API_KEY")
print(f"Key starts with: {api_key[:8]}...")  # Don't print the full key

Upload Failures

Error: UploadError: File too large

Solutions:

  • Check file size limits (50MB for documents, 1GB–10GB for videos depending on plan)
  • Compress or resize images before uploading
  • Use batch uploads for large collections

Rate Limiting

Error: RateLimitError: Rate limit exceeded

Solutions:

  • Implement exponential backoff retry logic
  • Use batch operations instead of individual requests
  • Contact support to increase rate limits
# The SDK handles retries automatically
async with AionVision(
    api_key=api_key,
    max_retries=3,  # Default is 3
) as client:
    result = await client.upload_one("image.jpg")

Connection Timeouts

Error: AionvisionTimeoutError: Operation timed out

Solutions:

  • Increase timeout settings for large uploads (default is 300 seconds)
  • Check network connectivity
  • Use streaming for large responses
# Increase timeout for large operations (default is 300s)
async with AionVision(
    api_key=api_key,
    timeout=600.0,  # 10 minutes
) as client:
    result = await client.upload_one("image.jpg")

Client Not Initialized

Error: RuntimeError: Client not initialized. Use 'async with AionVision(...) as client:'

Solutions:

  • The client must be used as an async context manager to initialize the HTTP connection
  • Use async with AionVision(...) as client: instead of client = AionVision(...)
  • For sync usage, use with SyncAionVision(...) as client:
# Correct: Use context manager
async with AionVision(api_key=api_key) as client:
    result = await client.upload_one("image.jpg")


# Wrong: Client not initialized
client = AionVision(api_key=api_key)
result = await client.upload_one("image.jpg")  # RuntimeError!

Connection Errors

Error: AionvisionConnectionError: Connection failed

Solutions:

  • Check your internet connection
  • Verify the API base URL is correct
  • If behind a proxy, configure proxy_url in ClientConfig
  • The SDK retries connection errors automatically (up to max_retries)

Related

Error Handling Guide

Exception hierarchy and handling patterns

Exceptions Reference

Complete list of SDK exceptions