Provider routing & fallback
Every published model can carry more than one vendor route. This page documents how a request picks one, what happens when it fails, and which vendor faults become which returned error.
How it works
A model has one active vendor route and, where a second vendor also carries the model, one or more backup routes. A request tries the active route first. If that vendor returns an infrastructure-level fault, the gateway retries the next candidate route automatically in the same request. The intermediate failure is never visible unless every candidate is exhausted.
A request-level fault (a rejected payload) never triggers this retry. Replaying an invalid request against a different vendor would not fix it, so the error is returned immediately.
Vendor status to returned error
The exact decision, by the vendor's real HTTP status:
| Vendor returns | Decision | Returned error |
|---|---|---|
5xx | Fail over to the next route | On the last candidate: 502 upstream_error |
429 | Fail over to the next route | On the last candidate: 429 rate_limit_exceeded |
401 / 403 | Fail over to the next route | A bad or expired vendor credential is never exposed. It is masked as: 502 upstream_error |
402 | Fail over to the next route | A vendor account out of funds is never exposed. It is masked as: 502 upstream_error |
400 / 404 / 422 | Return immediately, no retry | The vendor's own message, returned as-is. It describes the request, not an internal detail. |
A vendor fault's raw detail (account identifiers, internal balances, provider request ids) is never forwarded. Every infrastructure-level fault collapses to the generic message above, regardless of the vendor or the specific failure.
Fallback order and timing
Where a model carries more than one vendor route, routes are tried in a fixed priority order, filtered to routes that are currently healthy.
Details pending: a specific vendor's own selection order, health-check timing, and circuit-open thresholds are not yet confirmed against that vendor's own documentation. This section will be filled in once confirmed rather than guessed at now.
A route's health signal is debounced. A single failed probe does not immediately mark it unhealthy, and recovery also takes a small number of consecutive successful probes. A model's displayed status and the vendor selected for the next request can therefore briefly disagree while a health signal settles, by design.