When a model is available from more than one provider, Spro decides which provider serves each request. There are two routing strategies: failover and priority. Each workspace uses one of them.
The two strategies
| Strategy | What happens | Use it when |
|---|---|---|
| Failover (default) | Spro sends the request to the highest-priority provider. If that provider fails, Spro tries the other providers that serve the same model, in priority order. | You want the request to succeed even if one provider has an outage. |
| Priority | Spro always uses the highest-priority provider. If it fails, the request fails. | You need every request to go to one provider, for example to keep costs or data location predictable. |
A provider that fails is skipped for the next 60 seconds, so requests don't wait on a provider that is known to be down. Each gateway instance keeps its own short memory of failures.
Plain model names and pinned providers
How you name the model decides whether failover can happen at all.
- Plain slug, such as
gpt-oss-20b: any provider that serves the model can be used, so failover applies. - Pinned provider, such as
openai/gpt-oss-20b: the request must go to that provider. If it fails, you get the error back. Spro never switches a pinned request to another provider.
Fallback chains you send yourself
You can list fallback models in the request (models for the OpenAI-style API, fallbacks for the Anthropic Messages API). When you do:
- Spro tries your models in the order you gave them. Failover to other providers is not added on top of your list.
- A retired model is not called. Spro records it in the usage log with the error
model_retired, then moves to the next model in your list.
What appears in the usage log
When a request moves past a model that could not serve it, the usage log keeps the reason. The x-spro-fallback-from response header names the first model that was tried, and the usage log records the reasons in order. The reasons you may see are:
| Reason | Meaning |
|---|---|
model_retired | The model is retired and was skipped. |
model_not_found | The model isn't in the catalog. |
provider_<status> | The provider returned an error, such as provider_503. |
provider_unhealthy | The provider failed recently and was skipped for now. |
no_credential | No usable credential exists for that provider. |
unsupported_surface | The model does not support the endpoint you called. |
Choosing a strategy
The strategy is a workspace setting. Set it to priority if every request must go to the top provider, and leave it on failover otherwise. A change applies to new requests.
