# Fallbacks

Name the models to try in order when the first one fails.

1. [Name the models in models](#1-name-the-models-in-models).
2. [Read which one answered](#2-read-which-one-answered).
3. [Set the same list for every request](#3-set-the-same-list-for-every-request).

## 1. Name the models in models

Send `model` as usual, and add `models`: a list of more models, tried in order when `model` fails or is limited. The first one to answer ends the search.

| You send | Holds |
|---|---|
| `model` | the model you want |
| `models` | the models to try after it, in order: up to 200 names, each `lab/model` |

```python
import json
import os
import urllib.request

API_KEY = os.environ["OPENDUNES_API_KEY"]
ADDRESS = "https://opendunes.com/v1/chat/completions"
MODEL = "anthropic/claude-sonnet-4.5"
FALLBACKS = ["openai/gpt-5.4-mini", "google/gemini-2.5-flash"]
PROMPT = "Write a one-line welcome for a bakery in Tlemcen."

body = {
    "model": MODEL,
    "models": FALLBACKS,
    "messages": [{"role": "user", "content": PROMPT}],
}

request = urllib.request.Request(
    ADDRESS,
    data=json.dumps(body).encode(),
    headers={
        "Authorization": "Bearer " + API_KEY,
        "Content-Type": "application/json",
    },
)
with urllib.request.urlopen(request) as response:
    reply = json.load(response)

print(reply["model"])
print(reply["choices"][0]["message"]["content"])
print(reply["usage"]["cost"])
```

```javascript
const API_KEY = process.env.OPENDUNES_API_KEY;
const ADDRESS = "https://opendunes.com/v1/chat/completions";
const MODEL = "anthropic/claude-sonnet-4.5";
const FALLBACKS = ["openai/gpt-5.4-mini", "google/gemini-2.5-flash"];
const PROMPT = "Write a one-line welcome for a bakery in Tlemcen.";

const response = await fetch(ADDRESS, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: MODEL,
    models: FALLBACKS,
    messages: [{ role: "user", content: PROMPT }],
  }),
});
const reply = await response.json();

console.log(reply.model);
console.log(reply.choices[0].message.content);
console.log(reply.usage.cost);
```

```go
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

const (
	address   = "https://opendunes.com/v1/chat/completions"
	model     = "anthropic/claude-sonnet-4.5"
	fallback1 = "openai/gpt-5.4-mini"
	fallback2 = "google/gemini-2.5-flash"
	prompt    = "Write a one-line welcome for a bakery in Tlemcen."
)

func main() {
	apiKey := os.Getenv("OPENDUNES_API_KEY")

	body, err := json.Marshal(map[string]any{
		"model":  model,
		"models": []string{fallback1, fallback2},
		"messages": []any{
			map[string]any{"role": "user", "content": prompt},
		},
	})
	if err != nil {
		panic(err)
	}

	request, err := http.NewRequest("POST", address, bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	request.Header.Set("Authorization", "Bearer "+apiKey)
	request.Header.Set("Content-Type", "application/json")

	response, err := http.DefaultClient.Do(request)
	if err != nil {
		panic(err)
	}
	defer response.Body.Close()

	var reply struct {
		Model   string `json:"model"`
		Choices []struct {
			Message struct {
				Content string `json:"content"`
			} `json:"message"`
		} `json:"choices"`
		Usage struct {
			Cost float64 `json:"cost"`
		} `json:"usage"`
	}
	if err := json.NewDecoder(response.Body).Decode(&reply); err != nil {
		panic(err)
	}
	fmt.Println(reply.Model)
	fmt.Println(reply.Choices[0].Message.Content)
	fmt.Println(reply.Usage.Cost)
}
```

```bash cURL
ADDRESS="https://opendunes.com/v1/chat/completions"
MODEL="anthropic/claude-sonnet-4.5"
FALLBACK_1="openai/gpt-5.4-mini"
FALLBACK_2="google/gemini-2.5-flash"
PROMPT="Write a one-line welcome for a bakery in Tlemcen."

curl "$ADDRESS" \
  -H "Authorization: Bearer $OPENDUNES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$MODEL"'",
    "models": ["'"$FALLBACK_1"'", "'"$FALLBACK_2"'"],
    "messages": [
      {
        "role": "user",
        "content": "'"$PROMPT"'"
      }
    ]
  }'
```

<div class="do">
<p>Name fallbacks that can do the same job: the same kind of input, and an answer your code reads the same way.</p>
</div>

<div class="dont">
<p>Don't put a model the key may not use in <code>models</code>. The request is refused with a 403 that names it, even if the first model would have answered.</p>
</div>

## 2. Read which one answered

The answer's `model` names the one that served, as `lab/model`. When it is not the model you sent first, a fallback answered.

A fallback is charged at its own price, never the first model's. `usage.cost` is the charge of the model that served.

<div class="good-to-know">
<p>A free model takes no fallbacks.</p>
</div>

## 3. Set the same list for every request

To have the same fallbacks on every request without touching code, open the Gateway page of your dashboard and name up to three models. The list is kept for each API key.

A request that names its own `models` sets the dashboard's list aside for that request.

<div class="good-to-know">
<p>Fallbacks change the model. To change the company that serves the same model, see <a href="/docs/provider-routing">Provider routing</a>.</p>
</div>

## Errors

The body says why. What to do on every status: [Errors and retries](/docs/errors-and-retries).

| Status | Means |
|---|---|
| 400 | `models` is not a list of up to 200 model names |
| 402 | the balance cannot cover the request |
| 403 | a model you named is not one the key may use |
| 404 | no such model |
