Failover
How Speko transparently retries against runner-up providers when the primary fails.
Every routing decision returns a primary SelectedCandidate plus an ordered runnersUp list — the next-best providers for the same intent. If the primary throws, Speko retries against the next candidate. From the caller's perspective: one request, one response. From the response: failoverCount tells you how many providers it tried before one succeeded.
What counts as a failure
A candidate is considered failed if it:
- Throws a network or 5xx error.
- Returns no transcript / no audio / no completion text.
- Errors mid-stream.
Auth errors against BYOK keys also fail — Speko advances to the next candidate without retrying the current one.
What does not retry
- Request validation errors. Speko checks the request body before it selects a provider. A malformed body, a missing field or invalid
providerOptionsreturns a 400 at once, and no provider is called. - Auth errors against the Speko gateway itself. Your API key is invalid. That is not a routing problem.
A 4xx from a provider is not the same. For POST /v1/synthesize, a provider that refuses the request (a voice it does not know, text over its limit, a language it does not speak) is a failed candidate, and Speko tries the next one. After a provider refuses the voice, the later candidates use their own default voice. The exception, on a direct POST /v1/synthesize request, is a single bare vendor entry in constraints.allowedProviders.tts: the other models Speko adds for that vendor always get the voice you asked for, and when the vendor refuses that voice Speko stops and returns the refusal (422 ALL_PROVIDERS_FAILED) instead of audio in another voice. Fallback entries you list yourself keep the default voice rule, and so does speech inside a live call (a request whose x-session-id names one of your sessions), where a substituted voice beats silence. If every candidate refuses with a 4xx, Speko returns ALL_PROVIDERS_FAILED with status 422.
Failures after the first audio
For POST /v1/synthesize, the delivery mode decides what happens when a provider fails after it sent some audio.
- Stream (the default). Speko already sent that audio to you, so it cannot change the provider. The response stream ends with an error.
- Link (
delivery: "link"). Speko sends you nothing until the audio is complete, so it can try again:- Speko sends the same request to the same provider one more time. The voice and the price do not change.
- If that request also fails, Speko tries the next candidate. The next candidate uses its own default voice when it cannot speak yours.
- If no candidate finishes, you get the error of the first provider. Speko bills that request once, at the first provider's price.
Speko tries again only in two cases: the provider stops sending audio, or the connection to it fails. A refusal or a rate limit after the first audio stops recovery, because the same request would fail the same way. If this happens on the first candidate, you get that error. If it happens on a later candidate, you get the first candidate's error. Speko also starts no new attempt when less than 20 seconds of the request time limit are left.
When a later attempt finishes, Speko does not bill the failed attempts. It bills the request once, at the price of the provider that produced the audio. The provider, model and X-Speko-Failover-Count values in the response name that provider.
Pinned providers
For a direct POST /v1/synthesize request, a single vendor:model entry in constraints.allowedProviders.tts never fails over to another model. A single bare vendor entry fails over only to that vendor's other models, in the voice you asked for. Add more entries when you want failover across vendors or models. Speko ranks the listed entries by its benchmark scores; when none of them has scores, it tries them in the order you list them. A pinned model that Speko cannot price is the one exception: it is skipped and the next priced candidate serves, in its own voice.
Text too long for every candidate
For POST /v1/synthesize, Speko compares the text length with each candidate before it calls the provider. Speko skips a candidate when:
- The text is longer than the provider's per-request limit, for example 5,000 characters for ElevenLabs
eleven_v3. - The request uses
delivery: "link", and the provider is too slow to finish the text inside the request time limit.
A skipped candidate costs no provider call. If Speko skips every candidate, it returns 422 TEXT_TOO_LONG with textLength and maxChars, and bills nothing. Split the text into parts of at most maxChars characters, at sentence ends, and send each part as its own request.
All candidates exhausted
If every candidate in the failover chain fails, Speko returns ALL_PROVIDERS_FAILED with a list of the underlying errors. This is rare in practice and usually signals a wide-scale outage or an over-restrictive constraints.allowedProviders list.
Observability
- Response body:
failoverCount,provider,model,scoresRunId. - Response headers:
X-Speko-Failover-Count,X-Speko-Provider,X-Speko-Model,X-Speko-Scores-Run-Id. - Server logs:
[transcribe] failover deepgram/nova-2 → assemblyai/best: <error>.
If you see consistent non-zero failoverCount for a specific intent, check the dashboard provider grid — a BYOK key might be misconfigured, or a provider might be degraded for your region.