Provider Failover
Automatic fallback to backup providers when your primary provider is unavailable, ensuring maximum uptime for your AI applications.
Overview
Cencori automatically handles provider failures by retrying requests and falling back to alternative providers. This ensures your users never see an error when a single provider has issues.
Automatic Retries
Retries with exponential backoff before failover
Circuit Breaker
Skips failing providers to reduce latency
Model Mapping
Maps to equivalent models on fallback providers
How It Works
- 1Request arrives — Cencori routes to your requested model (e.g.,
gpt-5) - 2Primary fails — Retries up to 3x with exponential backoff (100ms, 200ms, 400ms)
- 3Fallback activated — Routes to your configured fallback provider with equivalent model
- 4Response returned — Includes
fallback_used: trueso you know
Configuration
Configure failover in your Project Settings → Infrastructure tab:
Failover Settings
Enable automatic fallback
Route to backup providers on failure
Fallback provider
Preferred backup when primary fails
Max retries before fallback
Number of retry attempts
Model Mapping
When falling back to another provider, Cencori maps your model to an equivalent:
| Original Model | → Anthropic | |
|---|---|---|
| gpt-5 | claude-opus-4 | gemini-3-pro |
| gpt-4o | claude-sonnet-4 | gemini-2.5-flash |
| claude-opus-4 | — | gemini-3-pro |
| gemini-3-pro | claude-opus-4 | — |
Response Format
When a fallback is used, the response includes additional fields:
Note on Streaming
For streaming responses, fallback_used is included in the first SSE chunk only.
Circuit Breaker
Cencori uses a circuit breaker pattern to prevent cascading failures:
Closed (Normal)
All requests go to the provider
Open (After 5 failures)
Provider skipped, requests go directly to fallback
Half-Open (After 60s)
One test request sent; if successful, circuit closes
Webhooks
Get notified when failover occurs by subscribing to the model.fallback webhook event in your project settings.