> ## 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 a prompt.

| Error | Extends | Raised when |
| - | - | - |
| `PromptNotFoundError` | `To11aiApiError` | The requested prompt does not exist (404 `PROMPT_NOT_FOUND`). |
| `LabelNotFoundError` | `To11aiApiError` | The label does not exist (404 `LABEL_NOT_FOUND`); `label` carries the rejected value. `latest` is the only label a prompt has. |
| `PromptHasNoVersionsError` | `To11aiApiError` | The prompt has no version yet (409 `PROMPT_HAS_NO_VERSIONS`); `reason` carries the `slug` and `prompt_id`. |
| `PromptPolicyViolationError` | `To11aiApiError` | A prompt policy blocked the operation (403 `POLICY_VIOLATION`). |

> [!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.

## 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(format="openai")

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.