Set a fallback model so your agent keeps running reliably even if the primary model provider degrades, times out, or goes down entirely. This guide covers configuring fallback, understanding routing behavior, and monitoring reroutes.

Why fallback matters

Model providers occasionally have outages, elevated latency, or rate-limit periods. Without a fallback, any of these situations means your agent simply fails every run until the primary provider recovers. With a fallback configured, Sublayr automatically reroutes requests to a secondary model, keeping your agent operational.

Configuring a fallback

Add a fallback field to your agent config:

name: support-agent
model: anthropic/claude
fallback: openai/gpt-4o

name: support-agent
model: anthropic/claude
fallback: openai/gpt-4o

name: support-agent
model: anthropic/claude
fallback: openai/gpt-4o

You can chain more than one fallback for additional resilience:

model: anthropic/claude
fallback:
  - openai/gpt-4o
  - mistral/large

model: anthropic/claude
fallback:
  - openai/gpt-4o
  - mistral/large

model: anthropic/claude
fallback:
  - openai/gpt-4o
  - mistral/large

Sublayr tries each model in order until one succeeds.

What triggers a reroute

By default, Sublayr reroutes to the fallback model when:

• The primary model times out (default: 30 seconds, configurable)

• The primary model returns a 5xx error

• The primary model returns a rate-limit (429) error

You can customize these triggers:

model: anthropic/claude
fallback: openai/gpt-4o
routing:
  timeout_seconds: 15
  retry_on: [timeout, rate_limit, server_error]

model: anthropic/claude
fallback: openai/gpt-4o
routing:
  timeout_seconds: 15
  retry_on: [timeout, rate_limit, server_error]

model: anthropic/claude
fallback: openai/gpt-4o
routing:
  timeout_seconds: 15
  retry_on: [timeout, rate_limit, server_error]

Automatic recovery

Once the primary model becomes available again, Sublayr automatically routes new requests back to it — you don't need to manually revert after an outage clears. This is checked on a rolling basis, typically every 60 seconds after a failover event.

Monitoring reroutes

Every reroute is logged and visible in your agent's traces, tagged with the reason (timeout, rate limit, server error) and which model ultimately handled the request. You can also set an alert to notify you whenever a reroute happens, which is useful for tracking primary-provider reliability over time:

sublayr alerts create --agent agt_4b81 --event reroute

sublayr alerts create --agent agt_4b81 --event reroute

sublayr alerts create --agent agt_4b81 --event reroute

Cost implications

Different models have different pricing. If your fallback model is more expensive than your primary, sustained outages on the primary could increase costs during that window. Budgets and spend alerts (see the Usage section) apply regardless of which model actually handled a given run, so cost caps remain enforced even during failover.