> ## 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 throws, grouped by the surface that raises them.

The SDK throws typed errors. All extend `To11aiError`; API errors extend `To11aiApiError`, which carries a `statusCode` and an `errorCode`. 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 throws 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 `statusCode`.           |
| `To11aiValidationError`         | `To11aiApiError` | The API rejected the request (400).                  |
| `To11aiAuthError`               | `To11aiApiError` | Authentication or authorization failed (401 or 403). |
| `To11aiRateLimitError`          | `To11aiApiError` | Rate limited (429). Carries `retryAfterSeconds`.     |
| `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, except `To11aiResponseValidationError`, which is currently exported only from the `@to11ai/sdk/errors` subpath.
</Note>

## Catching errors

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

```ts theme={null}
import { createClient, PromptNotFoundError } from "@to11ai/sdk";

const to11 = createClient({ env: "production", format: "openai" });

try {
  const prompt = await to11.prompts.render("welcome-message");
  console.log(prompt.messages);
} catch (error) {
  if (error instanceof PromptNotFoundError) {
    // The prompt slug does not resolve in this project and environment.
  } else {
    throw error;
  }
}
```