Scopix

Documentation

Troubleshooting

Common issues and solutions when using the Scopix SDK

Need Help?

If you can't find a solution here, reach out to support@scopix.ai 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
python
# Verify your API key
import os
api_key = os.getenv("SCOPIX_API_KEY")
print(f"Key starts with: {api_key[:8]}...")  # Don't print the full key

Upload Failures

Error: UploadError: File too large

Solutions:

  • Streaming uploads are capped at 100 MB per file for all media types
  • For larger files, use the presigned upload flow (up to 5 TB)
  • The SDK's client.files.upload() auto-selects the right strategy by file size
  • Use batch uploads for large collections of small files
  • Text extraction is capped at 500 MB per document. Larger PDFs/DOCX/TXT/MD upload fine but are marked text_extraction_status: "failed" and won't appear in semantic search

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
python
# The SDK handles retries automatically
async with Scopix(
    api_key=api_key,
    max_retries=3,  # Default is 3
) as client:
    result = await client.files.upload("image.jpg")

Connection Timeouts

Error: ScopixTimeoutError: Operation timed out

Solutions:

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

Client Not Initialized

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

Solutions:

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


# Wrong: Client not initialized
client = Scopix(api_key=api_key)
result = await client.files.upload("image.jpg")  # RuntimeError!

Connection Errors

Error: ScopixConnectionError: 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