> ## Documentation Index
> Fetch the complete documentation index at: https://to11.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> The typed error classes the SDK raises, grouped by the surface that raises them.

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). |

<Note>
  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.
</Note>

## Catching errors

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

```python theme={null}
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.
    ...
```