Error Handling

All SDK errors extend TouAIError. Each HTTP status code maps to a more specific exception class.

Common Exceptions

from touai import (
    TouAI,
    TouAIError,
    AuthenticationError,
    InsufficientCreditsError,
    PermissionDeniedError,
    NotFoundError,
    ConflictError,
    ValidationError,
    RateLimitError,
    ServerError,
    TimeoutError,
    ConnectionError,
)
 
try:
    results = client.context_hub.search("test")
except AuthenticationError:
    print("Invalid or expired credentials")
except InsufficientCreditsError:
    print("Not enough credits")
except RateLimitError as e:
    print(f"Retry after {e.retry_after}s")
except NotFoundError:
    print("Resource not found")
except ValidationError as e:
    print(e.message)
except ServerError:
    print("Server error")
except TouAIError as e:
    print(e.status_code, e.message, e.request_id, e.body)

Error Properties

All TouAIError subclasses include:

Property	Type	Description
`message`	`str`	Human-readable error description
`status_code`	`int \	None`
`body`	`Any`	Raw response body
`request_id`	`str \	None`

RateLimitError also includes:

Property	Type	Description
`retry_after`	`float \	None`

Automatic Retries

The SDK automatically retries on 429, 500, 502, 503, and 504 with exponential backoff. It respects the Retry-After header when present and uses max_retries to cap attempts.

Retries help with transient failures, but they will not rescue validation errors or invalid credentials. Keep your error handling explicit around auth and request payloads.

Auth Type Reference