Fallback

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.

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.

LLMs
Expert Models

All models (primary and fallbacks) must be valid models listed in the Models page.

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

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 endpoint to discover available providers.

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

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());

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:

{
  "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": "<model>@eu", "fallbacks": ["<model>@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.

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

Next Steps

Provider Routing

Let Eden AI choose which provider serves a model

Request Metadata

See every provider tried, and why

LLM Models

Browse available LLM models

Expert Model Providers

Discover available providers for each feature

V3 Documentation

Quick Start

Overview

LLMs

Expert Models

General

Organization

Data Governance

Integrations

Usage

Provider-level failover (LLM)

Things worth knowing

Seeing what was tried

Next Steps

Provider Routing

Request Metadata

LLM Models

Expert Model Providers

​Usage

​Provider-level failover (LLM)

​Things worth knowing

​Seeing what was tried

​Next Steps

Provider Routing

Request Metadata

LLM Models

Expert Model Providers

Usage

Provider-level failover (LLM)

Things worth knowing

Seeing what was tried

Next Steps