Errors

The SDK raises typed errors. All extend To11aiError; API errors extend To11aiApiError, which carries a status_code, an error_code, and details. Catch the specific class you care about and fall back to the base classes for the rest. The classes are grouped by where they come from. Common errors can surface on any call. Beyond those, a given operation only raises errors from its own surface — a prompt-management call never raises a prompt-resolution error like LabelNotFoundError, and vice versa.

Common errors

Any SDK call can raise these — they cover transport, authentication, and response validation regardless of the operation.

Error	Extends	Raised when
`To11aiError`	—	Base class for all SDK errors.
`To11aiApiError`	`To11aiError`	Base for API errors. Carries `status_code`.
`To11aiValidationError`	`To11aiApiError`	The API rejected the request (400).
`To11aiAuthError`	`To11aiApiError`	Authentication or authorization failed (401 or 403).
`To11aiRateLimitError`	`To11aiApiError`	Rate limited (429). Carries `retry_after_seconds`.
`To11aiNetworkError`	`To11aiError`	A network failure or timeout occurred.
`To11aiResponseValidationError`	`To11aiError`	A 2xx response body failed schema validation.

Prompt errors

Raised while rendering or resolving a prompt — including the environment resolution and policy checks that resolution runs through.

Error	Extends	Raised when
`PromptNotFoundError`	`To11aiApiError`	The requested prompt does not exist.
`PromptLabelNotRegisteredError`	`To11aiApiError`	The referenced prompt label is not registered.
`NoActiveReleaseError`	`To11aiApiError`	No release is active for the resolution target.
`PromptPolicyViolationError`	`To11aiApiError`	A prompt or environment policy blocked the operation.
`LabelNotFoundError`	`To11aiApiError`	The label the prompt resolves against does not exist.
`MissingLabelError`	`To11aiError`	No label supplied per call and no client `env` to fall back to (raised client-side).

Every error class above is importable from the main to11ai_sdk entry. Two behaviors are worth noting: only idempotent requests (GET, PUT, DELETE) are retried, so POST and PATCH are never auto-retried and can’t double-submit; and 2xx responses are validated against their schema, raising To11aiResponseValidationError on drift.

Catching errors

Catch the specific class for the case you handle, and let the base classes cover the rest:

from to11ai_sdk import create_client, PromptNotFoundError, To11aiAuthError

client = create_client(env="production", format="openai")

try:
    prompt = client.prompts.render("welcome-message")
    print(prompt["messages"])
except PromptNotFoundError:
    # The prompt slug does not resolve in this project and environment.
    ...
except To11aiAuthError:
    # Check that TO11_API_KEY is set and valid.
    ...

SDKs

Gateway

Common errors

Prompt errors

Catching errors

​Common errors

​Prompt errors

​Catching errors

Common errors

Prompt errors

Catching errors