Reserva automática

provider.fallback lista los modelos alternativos que se probarán, en orden, cuando el modelo principal falle en el upstream.

Configuración

fallback acepta un array de identificadores de modelo y se sitúa al mismo nivel que type, bajo provider. Como máximo 3 modelos; por encima, la petición devuelve 400.

cURL

Terminal


curl https://api.ofox.io/v1/chat/completions \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-5",
    "messages": [{ "role": "user", "content": "..." }],
    "extra_body": {
      "provider": {
        "fallback": ["openai/gpt-5.5", "google/gemini-2.5-pro"]
      }
    }
  }'

Python

fallback.py


client.chat.completions.create(
    model="anthropic/claude-sonnet-5",
    messages=[{"role": "user", "content": "..."}],
    extra_body={
        "extra_body": {
            "provider": {
                "fallback": ["openai/gpt-5.5", "google/gemini-2.5-pro"],
            }
        }
    },
)

TypeScript

fallback.ts


await client.chat.completions.create({
  model: 'anthropic/claude-sonnet-5',
  messages: [{ role: 'user', content: '...' }],
  extra_body: {
    provider: {
      fallback: ['openai/gpt-5.5', 'google/gemini-2.5-pro'],
    },
  },
} as any)

Con los SDK oficiales de OpenAI, extra_body debe estar presente como clave literal en el cuerpo de la petición. El SDK de TypeScript lo envía tal como se escribe en el objeto de parámetros. El argumento extra_body= del SDK de Python fusiona su contenido en el nivel superior del cuerpo, por lo que la clave debe anidarse un nivel más, o enviarse como cabecera.

Qué provoca una reserva

La reserva solo cubre los fallos que ocurren después de que el enrutamiento haya elegido un canal:

Situación	Comportamiento
El proveedor upstream devuelve un error	Cambia de modelo — se prueban en orden los de la lista y se devuelve el primero que funcione
Falla el propio enrutamiento (el modelo no existe, o el proveedor fijado no lo sirve)	Sin reserva — la petición termina de inmediato

La segunda fila conviene decirla con claridad: fijar provider.type en un proveedor que no sirve el modelo devuelve 400 provider_type_unavailable, e indicar un modelo inexistente devuelve 404 model_not_found. Ninguno llega a la lista de reserva. Qué errores del upstream provocan realmente una reserva depende del comportamiento de la pasarela, no de una lista fija.

Combinación con un proveedor fijado

fallback y type pueden enviarse juntos: type restringe dónde se ejecuta el modelo principal, y fallback cubre lo que ocurre si este falla:


{
  "model": "anthropic/claude-sonnet-5",
  "messages": [{ "role": "user", "content": "..." }],
  "extra_body": {
    "provider": {
      "type": "bedrock",
      "fallback": ["openai/gpt-5.5"]
    }
  }
}

Referencia completa de campos en Enrutamiento de proveedores.

Errores habituales

`error.type`	Condición
`invalid_request_error`	La lista `fallback` contiene más de 3 modelos.

Buenas prácticas

Elige alternativas de capacidad similar — para que la calidad se mantenga tras el cambio.
Alternativas de otro fabricante — los modelos de un mismo fabricante suelen caer a la vez.
Vigila con qué frecuencia salta — si salta a menudo, toca cambiar el modelo principal.