> ## 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 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 `promptId`. |
| `PromptPolicyViolationError` | `To11aiApiError` | A prompt policy blocked the operation (403 `POLICY_VIOLATION`). |

> [!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. `UnknownRoleError` is thrown while converting messages; see [Unknown roles](https://to11.ai/docs/reference/typescript-sdk/rendering-prompts.md#unknown-roles).

## 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({ 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.
  } else {
    throw error;
  }
}
```


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