> ## Documentation Index
> Fetch the complete documentation index at: https://edenai-docs-refresh-dead-model-ids.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Fallback
> Eden AI automatically handles fallback on both LLM and Universal AI / expert model requests.
export const TechArticleSchema = ({title, description, path, articleSection, about, proficiencyLevel = "Beginner", dependencies, keywords = [], datePublished, dateModified, image, inLanguage = "en"}) => {
const baseUrl = "https://www.edenai.co/docs";
const canonicalUrl = `${baseUrl}/${path}`.replace(/\/+$/, "");
const ogParams = new URLSearchParams({
division: articleSection || "",
title: title || "",
description: description || ""
});
const resolvedImage = image || `https://edenai.mintlify.app/_mintlify/api/og?${ogParams.toString()}`;
const data = {
"@context": "https://schema.org",
"@type": "TechArticle",
"@id": `${canonicalUrl}#techarticle`,
mainEntityOfPage: {
"@type": "WebPage",
"@id": canonicalUrl
},
headline: title,
name: title,
description: description,
url: canonicalUrl,
inLanguage: inLanguage,
isPartOf: {
"@type": "WebSite",
name: "Eden AI Documentation",
url: baseUrl
},
author: [{
"@type": "Organization",
name: "Eden AI",
url: "https://www.edenai.co/"
}],
publisher: {
"@type": "Organization",
name: "Eden AI",
url: "https://www.edenai.co/",
logo: {
"@type": "ImageObject",
url: "https://www.edenai.co/assets/logo.png"
}
}
};
if (articleSection) data.articleSection = articleSection;
if (about) data.about = {
"@type": "Thing",
name: about
};
if (proficiencyLevel) data.proficiencyLevel = proficiencyLevel;
if (dependencies) data.dependencies = dependencies;
if (keywords && keywords.length) data.keywords = keywords;
if (datePublished) data.datePublished = datePublished;
if (dateModified) data.dateModified = dateModified;
data.image = Array.isArray(resolvedImage) ? resolvedImage : [resolvedImage];
const json = JSON.stringify(data);
const schemaId = `techarticle-${canonicalUrl}`;
React.useEffect(() => {
if (typeof document === "undefined") return;
document.querySelectorAll(`script[data-schema-id="${schemaId}"]`).forEach(n => n.remove());
const script = document.createElement("script");
script.type = "application/ld+json";
script.dataset.schemaId = schemaId;
script.textContent = json;
document.head.appendChild(script);
return () => script.remove();
}, [json, schemaId]);
return null;
};
Eden AI automatically handles fallback on both LLM and Universal AI / expert model requests. If your primary model or provider fails (provider outage, rate limit, error), Eden AI retries with the next item in your `fallbacks` list -- no retry logic needed on your side.
There are **two independent layers** of failover, and knowing which is which saves a lot of confusion:
| Layer | What it retries | You control it with |
| -------------------------- | ------------------------------------------------------------------ | ------------------------- |
| **Models you name** | The next entry in your `fallbacks` list, meaning a different model | `fallbacks` |
| **Providers of one model** | A different provider selling the *same* model you requested | `routing.allow_fallbacks` |
The second layer only exists for models sold by more than one provider, and only when you let Eden AI choose the provider. See [Provider Routing](/v3/llms/provider-routing).
## Usage
Add a `fallbacks` array to your request with one or more backup models (LLM) or providers (expert models). If the primary `model` fails, Eden AI will try each fallback in order.
`fallbacks` accepts at most **3** entries. Sending more returns a `422`.
All models (primary and fallbacks) must be valid models listed in the [Models](/v3/llms/listing-models) page.
```python Python theme={null}
import requests
url = "https://api.edenai.run/v3/chat/completions"
headers = {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json",
}
payload = {
"model": "google/gemini-2.5-pro",
"fallbacks": ["openai/gpt-4o"],
"messages": [
{"role": "user", "content": [{"type": "text", "text": "hi"}]}
],
"reasoning_effort": "none",
}
response = requests.post(url, headers=headers, json=payload)
print(response.status_code)
print(response.json())
```
```bash cURL theme={null}
curl -X POST https://api.edenai.run/v3/chat/completions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "google/gemini-2.5-pro",
"fallbacks": ["openai/gpt-4o"],
"messages": [{"role": "user", "content": [{"type": "text", "text": "hi"}]}],
"reasoning_effort": "none"
}'
```
All providers (primary and fallbacks) must support the same feature and subfeature. Use the [Listing Models](/v3/expert-models/listing-models) endpoint to discover available providers.
```python Python theme={null}
import requests
url = "https://api.edenai.run/v3/universal-ai"
headers = {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json",
}
payload = {
"model": "text/moderation/microsoft",
"fallbacks": ["text/moderation/google"],
"input": {"text": "Text to moderate"}
}
response = requests.post(url, headers=headers, json=payload)
print(response.status_code)
print(response.json())
```
```javascript JavaScript theme={null}
const response = await fetch("https://api.edenai.run/v3/universal-ai", {
method: "POST",
headers: {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
},
body: JSON.stringify({
model: "text/moderation/microsoft",
fallbacks: ["text/moderation/google"],
input: { text: "Text to moderate" }
})
});
console.log(response.status);
console.log(await response.json());
```
```bash cURL theme={null}
curl -X POST https://api.edenai.run/v3/universal-ai \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "text/moderation/microsoft",
"fallbacks": ["text/moderation/google"],
"input": {"text": "Text to moderate"}
}'
```
## Provider-level failover (LLM)
When you name a model **without** a provider (`gpt-5.6-sol` rather than `openai/gpt-5.6-sol`) Eden AI chooses the provider, and will try a different provider of that same model if the chosen one fails. This happens whether or not you supplied a `fallbacks` list.
To turn it off and have the request fail on the first provider instead:
```json theme={null}
{
"model": "gpt-5.6-sol",
"messages": [{"role": "user", "content": "hi"}],
"routing": {"allow_fallbacks": false}
}
```
`routing.allow_fallbacks` governs **other providers of the model you requested**. It never drops the models you listed in `fallbacks`. Those are your own choice and are always kept, even with `allow_fallbacks: false`.
## Things worth knowing
* **Repeats are kept, not deduplicated.** Listing the same model twice (`["a/m", "b/m", "a/m"]`) means it is genuinely attempted twice. A rate limit or a 5xx does not repeat deterministically, and Eden AI never re-attempts the *same* target on its own, so a deliberate repeat is the only way to get one. Trying a *different* provider of the same model is a separate mechanism: provider-level failover, which applies to provider-less names unless you set `routing.allow_fallbacks: false` (see above).
* **A provider-less name works in `fallbacks` too.** It resolves to one provider of that model, so `{"model": "openai/gpt-4o", "fallbacks": ["gpt-5.6-sol"]}` is valid.
* **Region tags are per entry.** `{"model": "@eu", "fallbacks": ["@us"]}` is two attempts in two regions, not one model with one region.
* **Failed attempts cost nothing.** You are billed only for the attempt that produced a response.
## Seeing what was tried
Send `x-edenai-metadata: enabled` and the response reports every attempt in order, each with the provider and its HTTP status, so a fallback is visible rather than inferred from latency.
```json theme={null}
"edenai_metadata": {
"attempt": 2,
"attempts": [
{"provider": "azure", "model": "azure/gpt-5.6-sol", "status": 429, "region": "global"},
{"provider": "openai", "model": "openai/gpt-5.6-sol", "status": 200, "region": "global"}
]
}
```
`attempt: 2` means the first provider failed and the second served. See [Request Metadata](/v3/llms/request-metadata).
## Next Steps
Let Eden AI choose which provider serves a model
See every provider tried, and why
Browse available LLM models
Discover available providers for each feature