Radondocs

Errors

Every typed error in @radonsdk/ai — the stable .code on each, what causes it, and the extra fields some carry (retryAfterSec, rawArguments, packageName, status).

Every failure Radon AI throws is a subclass of AIError with a stable .code string. Branch on the class (instanceof) or the code — never on message text, which can change.

handle-errors.ts
import { RateLimitError, AuthenticationError, AIError } from "@radonsdk/ai";

try {
  await ai.chat({ messages });
} catch (err) {
  if (err instanceof RateLimitError) {
    await sleep((err.retryAfterSec ?? 1) * 1000);
  } else if (err instanceof AuthenticationError) {
    // bad or missing API key
  } else if (err instanceof AIError) {
    console.error(err.code, err.message); // any other Radon error
  }
}

Base class

AIErrorcode: AIErrorCode

The base of every error below. err.code is the stable machine-readable string; err.message is human-readable. Catch this to handle any Radon AI failure generically.

Every error

Class.codeCause
InvalidConfigErrorinvalid_configMisconfiguration caught before any network call — empty providers, an unknown defaultProvider, or a missing embedding model.
ProviderNotFoundErrorprovider_not_foundA slug was requested that isn't registered as a built-in or via registerProvider.
ProviderNotConfiguredErrorprovider_not_configuredA provider was used that the app never added to its providers config.
LicenseRequiredErrorlicense_requiredA Pro provider or Pro feature was used without a license. Set licenseKey and call await ai.init().
LicenseInvalidErrorlicense_invalidThe license key could not be verified (invalid, revoked, or the verify endpoint was unreachable — fail-closed).
UnsupportedOperationErrorunsupported_operationA provider was asked to do something it genuinely can't (e.g. embed() on a chat-only provider). Reflected in provider.capabilities.
AuthenticationErrorauthentication_failedThe provider rejected the credentials (HTTP 401/403) — bad or expired API key.
ProviderApiErrorprovider_errorThe provider's API returned an error (bad request, model not found, 5xx). Carries status, providerCode, raw.
RateLimitErrorrate_limitedThe provider signalled a rate limit (HTTP 429). Carries retryAfterSec when reported.
ContextLengthExceededErrorcontext_length_exceededThe request exceeded the model's context window.
NetworkErrornetwork_errorA transport failure reaching the provider — DNS, timeout, TLS, connection reset. Carries cause.
InvalidToolArgumentsErrorinvalid_tool_argumentsA model produced tool-call arguments that weren't valid JSON. Carries rawArguments.
StreamErrorstream_errorA streaming response broke mid-flight (malformed SSE, transport reset). Carries cause.
NativeClientUnavailableErrornative_client_unavailablenative() was called but the provider's official SDK isn't installed. Carries packageName.

content_filtered

AIErrorCode also includes content_filtered. Safety-filtered generations are normally surfaced as a finishReason of "content_filter" on a successful ChatResult rather than thrown — inspect res.finishReason.

Errors that carry extra fields

Some errors expose structured data beyond code and message.

ProviderApiError

providerstring

The provider slug the error came from.

statusnumber | undefined

The HTTP status, when the failure came from an HTTP response.

providerCodestring | undefined

The provider's own machine error code, if it returned one.

rawunknown

The raw provider response body (parsed JSON or text) — an escape hatch for debugging.

RateLimitError

providerstring

The provider that rate-limited you.

retryAfterSecnumber | undefined

Seconds until you may retry, from the provider's Retry-After header when present.

if (err instanceof RateLimitError) {
  await sleep((err.retryAfterSec ?? 5) * 1000);
}

InvalidToolArgumentsError

providerstring

The provider whose model produced the bad arguments.

toolNamestring

Which tool the malformed call was for.

rawArgumentsstring

The raw string the model produced, for logging or an automated repair attempt.

NativeClientUnavailableError

providerstring

The provider whose native SDK is missing.

packageNamestring

The exact package to install — the message includes the npm install command. Or fall back to rawClient(), which needs no dependency.

UnsupportedOperationError

providerstring

The provider that can't do it.

operationstring

The operation attempted (e.g. "embed", "streamChat").

NetworkError and StreamError

Both carry provider and a cause (the underlying transport error). A caller-initiated abort during a stream is surfaced verbatim (an AbortError), not wrapped as a StreamError.

Fallback and errors

In a fallback chain, most errors advance to the next provider, but LicenseRequiredError and InvalidConfigError re-throw immediately — trying another provider can't fix a licensing or configuration problem.

Next steps

API reference

Every method and option that can throw these.

Fallback chains

How errors drive automatic provider retries.

API reference

Every method, option, and return type in @radonsdk/ai — the RadonAI class, ChatOptions, EmbedOptions, ChatResult, the StreamChunk union, and ChatStream.

On this page

Base classEvery errorErrors that carry extra fieldsProviderApiErrorRateLimitErrorInvalidToolArgumentsErrorNativeClientUnavailableErrorUnsupportedOperationErrorNetworkError and StreamErrorFallback and errorsNext steps