Errors

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

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.

Catching errors

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

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;
  }
}

SDKs

Gateway

Common errors

Prompt errors

Catching errors

​Common errors

​Prompt errors

​Catching errors

Common errors

Prompt errors

Catching errors