Fallback chains
Automatically retry a failed chat() on backup providers — a Pro feature. How the chain works, which errors stop it, and why streaming doesn't support it.
Pro A fallback chain lets ai.chat() try backup providers in
order if the primary fails — so a provider outage or rate limit degrades to a
different vendor instead of an error. Add the fallback array to any chat()
call.
Fallback is a Pro feature on any provider — set a licenseKey and call
await ai.init() first. Passing a non-empty fallback triggers the gate. See
Free vs. Pro.
// Try OpenAI; if it fails, fall back to Anthropic, then Groq — same call.
const res = await ai.chat({
messages,
provider: "openai",
fallback: ["anthropic", "groq"],
});
res.provider; // whichever provider actually answeredHow the chain works
Radon builds an ordered chain: the primary (whatever provider, or the
default, resolves to) followed by each slug in fallback. It calls each in turn
and returns the first success. If every provider in the chain fails, the
last error is thrown.
// Chain: ["openai", "anthropic", "groq"]
// → try openai; on failure try anthropic; on failure try groq;
// return the first that succeeds, else throw groq's error.Every provider in the chain must be configured in your providers block, and
any Pro provider in the chain still requires the license (which you have, since
fallback itself is Pro).
The result tells you who answered
Read res.provider and res.model to see which provider actually produced the
result — useful for logging and cost attribution when a fallback fired.
Which errors stop the chain
Most failures — a rate limit, a provider API error, a network blip — cause Radon to move on to the next provider. But two kinds of error are not retried, because trying another provider can't fix them:
LicenseRequiredErrornot retriedA licensing problem is global, not provider-specific — it re-throws immediately.
InvalidConfigErrornot retriedA misconfiguration won't be fixed by a different provider — it re-throws immediately.
Everything else (RateLimitError, ProviderApiError, AuthenticationError,
NetworkError, ContextLengthExceededError, …) advances the chain to the next
provider.
Streaming does not support fallback
fallback is honored by chat() only
A stream commits to a single provider — its provider
(or the default) — because output has already started flowing to the caller by the
time a mid-stream failure could occur. If you pass fallback to stream() it is
ignored (its presence still trips the Pro-feature gate). To retry a stream on a
different provider, wrap ai.stream() in your own try/catch and call it again.
// ❌ fallback is ignored here — stream() uses only "openai".
ai.stream({ messages, provider: "openai", fallback: ["anthropic"] });
// ✅ retry yourself:
async function streamWithRetry(messages) {
for (const provider of ["openai", "anthropic", "groq"]) {
try {
return ai.stream({ messages, provider });
} catch { /* try the next */ }
}
throw new Error("all providers failed");
}Next steps
Structured output
Ask for JSON or a schema-conforming object with responseFormat — a Pro feature. JSON mode, JSON Schema, what each provider guarantees, and the Anthropic caveat.
Providers
All 10 AI providers — env var, default model, capabilities, base URL, native() package, and quirks. OpenAI, Anthropic, Groq (free) plus seven Pro providers.