This guide will cover defining aliases (config-only today) that fail over across providers, and how the gateway retries and falls back. Resilience in Roadie comes from aliases — a project-level name that maps to an ordered list of targets across providers — combined with per-target retries, static fallback, and a circuit breaker. The model is in Models, aliases & fallback; this guide is how to reason about and design it.
Aliases are config-only today: they live in your project’s gateway configuration. There is no model-alias management API and no dashboard editor yet, and routing is static — there is no dynamic or latency-based selection.

​
Direct id vs alias

The model field on a chat, embeddings, or image request accepts either:
  • A direct provider/model id (openai/gpt-4o). It resolves to a single target. Any failure to resolve it — an unknown model, a key restriction, a missing capability, or no provider credential — is a hard error, because there is nothing to fall over to.
  • A project alias (smart). It expands to an ordered list of targets and can fail over across providers.
Use an alias whenever you want cross-provider resilience; use a direct id when you deliberately want one specific model with no fallback.

​
Designing an alias

An alias is an ordered target list. A smart alias might be:
Order matters — the gateway tries targets top to bottom. Put your preferred target first and a cross-provider backup second so an OpenAI incident fails over to Anthropic. A target can optionally pin a specific provider credentialId if you keep more than one key per provider. At request time the gateway expands the alias to its eligible targets, skipping any that are not in the environment catalog, are excluded by the key’s allowed_models, lack a capability the request needs (tools, JSON schema, vision), or have no configured provider credential. The alias still routes as long as one eligible target remains; if none do, the request fails no_eligible_target.
A backup target only helps if it is actually usable. Make sure every provider in the alias has a validated BYOK credential and that the models are in the environment catalog — otherwise the target is silently skipped.

​
How retries and fallback interact

Within a single request the gateway distinguishes two failure classes:
  • Retryable faults — provider overload, 5xx, and timeouts. The gateway retries the current target with exponential backoff and full jitter (up to 2 retries, each wait capped at ~2 s), then fails over to the next target in the list.
  • Non-retryable faults — an invalid request, authentication, permission, or content-filter error. These are terminal: the request finalizes on that error with no retry and no fallover, because retrying cannot help.
A provider rate_limited is retried inline only when its retry-after is short (≤ 2 s); a longer one falls over instead of stalling the request.

​
Read the gateway block

Every response carries a gateway block that tells you what routing did:
  • 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.
Watch fallback_used in your request logs: a rising rate means your primary target is degrading and the backup is carrying traffic.

​
The 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:
  • It 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, so a flapping provider stops adding latency.
  • Every 15 seconds a single probe request is allowed through; a success closes the breaker, a failure re-opens the 15-second clock.
The breaker is deliberately approximate — under concurrent load a trip may land a request or two early or late — which is well within tolerance for an error-rate breaker.

Models, aliases & fallback

The routing model and error codes.

Cross-provider fallback tutorial

Fail over from OpenAI to Anthropic step by step.

Providers & BYOK

Make sure every target has a usable credential.

Errors & retries

Which failures are retried and which are terminal.