Errors & Retries

Exception hierarchy

All SDK exceptions inherit from AISDKError, so you can catch everything with a single except clause or handle specific cases individually.

Exception	When it's raised
AISDKError	Base class for all SDK errors
AuthenticationError	Missing or invalid API key
NotFoundError	Assistant or app ID not found (404)
ValidationError	Invalid request body (422)
ServerError	Server-side failure (5xx after all retries)
APIConnectionError	Network failure — could not reach the API
APIResponseError	Unexpected response format

Catching exceptions

from custodian_labs import create_assistant
from custodian_labs import (
    AuthenticationError,
    NotFoundError,
    ValidationError,
    ServerError,
    APIConnectionError,
    AISDKError,
)

try:
    app = create_assistant(model="gpt-4o", prompt="You are a helpful assistant.")
    response = app.chat("Hello")
except AuthenticationError:
    print("Invalid or missing API key. Check CUSTODIAN_SDK_API_KEY.")
except NotFoundError:
    print("Assistant or app not found.")
except ValidationError as e:
    print(f"Bad request: {e}")
except ServerError:
    print("Server error after retries. Try again later.")
except APIConnectionError:
    print("Could not reach the API. Check your network or base URL.")
except AISDKError as e:
    print(f"Unexpected SDK error: {e}")

Retry behaviour

The SDK automatically retries failed requests on 5xx server errors using exponential backoff.

Setting	Default	Constructor param
max_retries	2	max_retries=
Base backoff delay	0.25s	—
Backoff formula	0.25 × 2^attempt	—

With the default max_retries=2, the SDK makes up to 3 attempts total — the first attempt plus two retries — waiting 0.25s then 0.5s between them.

4xx errors are not retried. A 401, 404, or 422 indicates a problem with your request that won't resolve by retrying.

Adjusting retries

from custodian_labs import create_assistant

# Disable retries entirely
app = create_assistant(model="gpt-4o", prompt="...", max_retries=0)

# Retry up to 4 times
app = create_assistant(model="gpt-4o", prompt="...", max_retries=4)

Timeout

The default request timeout is 30 seconds. Adjust it if you're uploading large files or working with slow networks:

app = create_assistant(
    model="gpt-4o",
    prompt="...",
    timeout=60.0,  # seconds
)