Routing overview

For models hosted by more than one EU provider, the gateway picks exactly one per request. You can stay hands-off (the gateway's defaults are sane), give a strategy hint, or take total control with provider pinning.

The five-step decision

flowchart TD
  Req[Request arrives] --> Pin{X-CleverRouter-Provider set?}
  Pin -- yes --> CheckHost{Does that provider<br/>host this model?}
  CheckHost -- no --> Err400[400 provider_unsupported]
  CheckHost -- yes --> UsePin[Use pinned provider]
  Pin -- no --> Sort[Sort by model_providers.priority ASC]
  Sort --> Health{Provider healthy<br/>in last probe?}
  Health -- no --> NextProvider[Skip, try next]
  Health -- yes --> Disabled{enabled = true AND<br/>deprecated_at IS NULL?}
  Disabled -- no --> NextProvider
  Disabled -- yes --> Use[Use provider]
  NextProvider --> Health

Word version:

1. Explicit pin (X-CleverRouter-Provider) wins if the model is hosted there. If not: 400 provider_unsupported — no silent fallback.
2. Priority sort on model_providers.priority ASC — lowest wins.
3. Health filter — providers that were down in the last health probe are skipped (unless all are down).
4. Disabled / deprecated — enabled=false mappings are ignored. deprecated_at IS NOT NULL returns 410 Gone.
5. Strategy hint (X-CleverRouter-Strategy) refines step 2 when multiple providers tie on priority.

What we deliberately don't do

Inspecting the chosen provider

Every successful response carries:

X-CleverRouter-Provider: scaleway
X-Request-Id: 0193adc8-…

Combine the two and you can correlate any call with the dashboard's request log.

Streaming and failover

Three sections that follow this

• Strategies — what cheapest / fastest / best actually mean.
• Provider pinning — when to take control and how.
• Retry & timeout — 429 / 5xx policy, CRTimeoutError.