Error Handling

Use this page to identify common SDK and API errors, understand what they mean, and decide how your application should handle them.

Error Codes

Code or error	SDK exception	What it usually means	What to check
401	AuthenticationError	The API key is missing, invalid, expired, or not available to the running process.	Check CUSTODIAN_SDK_API_KEY, rotate the key if needed, and restart your application.
404	NotFoundError	The assistant, app, or resource does not exist or is not accessible with the current key.	Check the assistant or app ID and confirm the key belongs to the correct account or environment.
422	ValidationError	The request payload is invalid.	Check required fields such as model, prompt, examples, file path, or message content.
5xx	ServerError	The API returned a server-side error after retries.	Retry later or check service status.
Network error	APIConnectionError	The SDK could not reach the API.	Check network access, firewall settings, and CUSTODIAN_SDK_BASE_URL.
Other 4xx	APIResponseError	The API returned an unclassified client-side error.	Inspect the error payload for details.

Error Details

Every SDK error may include:

• message
• status_code
• endpoint
• payload

These fields are useful for logging and debugging:

except AISDKError as error:
    print(error.status_code)
    print(error.endpoint)
    print(error.payload)

SDK Exception Types

All SDK exceptions inherit from AISDKError.

Exception	When it is raised
AuthenticationError	The API key is missing or invalid. Maps to 401 responses or missing local configuration.
NotFoundError	The requested assistant, app, or resource was not found. Maps to 404.
ValidationError	The request is invalid. Maps to 422.
ServerError	The API returned a server-side error. Maps to 5xx responses after retries.
APIConnectionError	The SDK could not reach the API after retries.
APIResponseError	The API returned another unclassified error response.
AISDKError	Base class for all SDK exceptions.

Catch Errors

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

try:
    app = create_assistant(
        model="gpt-4o",
        prompt="You are a helpful assistant.",
    )

    response = app.chat("Hello")
    print(response.response)

except AuthenticationError:
    print("Check your API key configuration.")

except NotFoundError:
    print("The requested assistant or app was not found.")

except ValidationError as error:
    print(f"Check the request body: {error}")

except ServerError:
    print("The API returned a server error. Try again later.")

except APIConnectionError:
    print("Could not reach the API. Check your network or base URL.")

except AISDKError as error:
    print(f"Unexpected SDK error: {error}")

Retry Behavior

The SDK automatically retries:

• Network request errors.
• 5xx server errors.

The SDK does not retry:

• 401 authentication errors.
• 404 not found errors.
• 422 validation errors.
• Other 4xx request errors.

By default, the SDK uses:

Setting	Default
timeout	30.0 seconds
max_retries	2
retry_backoff	0.25 seconds

With max_retries=2, the SDK makes up to three attempts total: the first request plus two retries.

Configure Timeout and Retries

You can pass retry and timeout settings to create_assistant() or Custodian:

from custodian_labs import create_assistant

app = create_assistant(
    model="gpt-4o",
    prompt="You are a helpful assistant.",
    timeout=60.0,
    max_retries=4,
)

To disable retries:

app = create_assistant(
    model="gpt-4o",
    prompt="You are a helpful assistant.",
    max_retries=0,
)

Common Issues

Missing API key

Set CUSTODIAN_SDK_API_KEY in the same terminal or runtime where your application starts.

Invalid API URL

Check CUSTODIAN_SDK_BASE_URL if the SDK cannot reach the API. Restart your application after changing the value.

Import error

If Python cannot import custodian_labs, confirm that your virtual environment is active and reinstall the package:

python -m pip install --upgrade custodian-labs

Next Steps

• Authentication: configure your API key and API URL.
• Chat Sessions: understand chat response fields.