Models, aliases & fallback

The model field of a chat, embeddings, or image request accepts either an explicit id or a project-defined alias.

Direct model ids

An explicit id is provider/model, for example:

openai/gpt-4o
openai/gpt-4o-mini
openai/text-embedding-3-small
openai/gpt-image-1
anthropic/claude-sonnet-5

The exact models available to a key are the environment’s catalog, narrowed by any key restriction. List them at runtime:

GET /v1/models
Authorization: Bearer rd_sk_prod_…

Each entry carries the model’s capabilities (context window, modalities, tools, JSON schema, streaming). See the models endpoint. A direct id resolves to a single target. Any failure to resolve it — an unknown model, a key restriction, or a missing capability for the request — is a hard error, because there is nothing to fall over to.

Aliases

An alias is a project-level name (like smart or fast) that maps to an ordered list of targets. Requesting an alias decouples your code from a specific provider or model:

snippets/node/alias.ts

import { createClient } from './client.js';

export async function chatViaAlias(): Promise<{ text: string; fallbackUsed: boolean }> {
  const roadie = createClient();

  const res = await roadie.chat.create({
    model: 'smart',
    messages: [{ role: 'user', content: 'Say hello via my routing alias.' }],
  });

  return {
    text: res.message.content.map((part) => part.text).join(''),
    fallbackUsed: res.gateway?.fallback_used ?? false,
  };
}

A smart alias might resolve to:

{
  "alias": "smart",
  "targets": [
    { "provider": "openai", "model": "gpt-4o" },
    { "provider": "anthropic", "model": "claude-sonnet-5" }
  ]
}

Aliases are config-only today: they live in your project’s gateway configuration. There is no model-alias management API and no dashboard editor for them yet.

When an alias is requested, the gateway expands it to its eligible targets. A target is skipped when it is not in the environment catalog, is excluded by the key’s model allowlist, lacks a capability the request needs (tools, JSON schema, vision), or has no configured provider credential. The alias still routes as long as one eligible target remains; if none do, the request fails not_found_error / no_eligible_target.

Fallback and retries

Fallback is static and ordered — the gateway tries an alias’s targets in the order they are configured. There is no dynamic or latency-based routing.

On a retryable provider fault (overload, 5xx, timeout — the fallback-eligible classes) the gateway retries the current target with exponential backoff and jitter (up to 2 retries, capped at ~2s per wait), then fails over to the next target.
A non-retryable fault (an invalid request, authentication, permission, or content filter) is terminal and does not trigger fallover.

The response’s gateway block tells you what happened:

{ "gateway": { "fallback_used": true, "retries": 1, "latency_ms": 1840 } }

fallback_used — whether a target other than the first served the request.
retries — how many retry attempts were made.
latency_ms — total gateway-observed latency.

A direct provider/model request has no fallback list — it is a single target. Use an alias when you want cross-provider resilience.

Circuit breaker

Each (project, provider, model) target has a Redis-backed circuit breaker so every gateway instance shares one view of a provider’s health. A target opens after a sustained error rate (at least 50% failures over at least 20 requests in a rolling 30-second window). While open, the target is skipped straight to the next fallback target; every 15 seconds a single probe request is allowed through — a success closes the breaker, a failure re-opens the clock. The breaker is deliberately approximate, so a trip may land a request or two early or late under concurrent load. For an end-to-end walkthrough, see the routing and fallback guide and the cross-provider fallback tutorial.

Embeddings

Only embeddings-capable targets are eligible for POST /v1/embeddings. An embeddings request to a chat-only model (or a provider without an embeddings API) resolves to no target and is rejected not_found_error / embeddings_not_supported before any provider call.

Get started

Core concepts

Guides

SDKs

Models, aliases & fallback

Direct model ids

Aliases

Fallback and retries

Circuit breaker

Embeddings

​Direct model ids

​Aliases

​Fallback and retries

​Circuit breaker

​Embeddings

Direct model ids

Aliases

Fallback and retries

Circuit breaker

Embeddings