Overview
A model step can name a fallback model. If the primary model fails (an outage, a rate limit, a
refusal), the fallback runs with its own parameters, and the workflow continues with its result.
How it works
- The primary model runs with the step’s
params.
- If it fails, the fallback model runs with the fallback’s
params.
- If both fail, the step fails.
Later steps don’t need to know which model answered: $.<step_id>.primary is the fallback’s
result when the fallback ran.
Configuration
Add a fallback object to a model step. Map the inputs again in the fallback’s params, because
the second model often takes different parameter names:
The full workflow is example 2 on the overview.
Fallback properties
Detecting fallback usage
When a step has a fallback, the execution’s step_outputs has an extra entry <step_id>_fallback:
fallback.reason is primary_failed when the fallback ran and not_triggered when the primary
model succeeded.
Best practices
- Pick a fallback that returns the same kind of output (an image URL for an image step).
- Use fallbacks on steps your product depends on, especially video and LLM steps.
- Watch
primary_failed in your results to spot a primary model that fails often.
- Check the fallback model’s price; it may differ from the primary’s.
Last modified on October 7, 2026
