Error Handling

All SDK errors extend TouAIError and are importable from touai. 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.connectors.search("test")
except AuthenticationError:
    print("Invalid or expired API key")
except InsufficientCreditsError as e:
    print(f"Not enough credits (reason: {e.reason})")
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)

Exception Classes

Class	Raised For
`AuthenticationError`	`401` — invalid or expired API key
`PermissionDeniedError`	`403` — insufficient permissions
`ApiKeyEntitlementRequired`	`403` — the organization has no API key entitlement (top up or subscribe in the console); subclass of `PermissionDeniedError`
`InsufficientCreditsError`	`402` — not enough credits; carries `requires_topup`, `reason`, `max_allowed_credits`
`NotFoundError`	the resource does not exist
`ValidationError`	`400` / `422` — request validation failed
`ConflictError`	`409` — conflicting state
`ConnectorSetupRequired`	`409` — the connector must be configured in the web console first; carries `setup_url`; subclass of `ConflictError`
`PlaygroundQuotaExceeded`	`409` — console playground quota is full (never raised for SDK/API-key traffic); subclass of `ConflictError`
`GoneError`	`410` — the endpoint or resource was retired; the message names the replacement
`RateLimitError`	`429` — too many requests; carries `retry_after`
`ServerError`	`5xx` — server-side error
`BillingFrozenError`	`503` — billing is temporarily frozen during an incident; subclass of `ServerError`
`TimeoutError`	request timed out; also subclasses the builtin `TimeoutError`
`ConnectionError`	network connection failed

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`
`error_code`	`str \	None`

Automatic Retries

The SDK retries 429 responses for every request, and 500, 502, 503, 504 for requests that are safe to replay (GET, or writes carrying an Idempotency-Key), 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