High Availability

Path: Settings → AI Gateway

Keep your agent answering when a model provider throttles or has an outage, and the same failover covers your task agents. Foldspace fails over to the next healthy model and key automatically, usually without the end user noticing.

High availability is the uptime half of model routing. Token Quotas control how much your agents spend; high availability keeps them responding when a provider becomes unavailable.

What failover handles

A model becomes unavailable in two ways. Both are transient, and failover masks them by moving to the next healthy option. The codes below are how Google’s Gemini API titles them; OpenAI returns the equivalent HTTP statuses.

• Capacity (429 RESOURCE_EXHAUSTED): the provider’s shared capacity is exhausted, or your key is being throttled. Foldspace retries briefly, then moves to the next option. If it’s your key’s own rate limit, that key gets a short cooldown while the next key or model takes over.
• Outage (503 UNAVAILABLE, 500 INTERNAL, 504 DEADLINE_EXCEEDED, 408): the provider times out or is down. Same handling: a brief retry, then the next option.

Failover order

Each request runs against an ordered list of options, where every option is a model plus one of your provider keys. Requests hit your key pool first: if you’ve added more than one key for a provider, Foldspace spreads across those keys before falling back further. The order is:

1. Requested model, your key(s). Every key you’ve added for that model’s provider.
2. A different provider, your key. If you have a key for the other provider, Foldspace tries its peer model there (see Model pairs).
3. A different model on the same provider, your key.
4. The Foldspace platform key. A last resort, used only when every one of your keys is exhausted and platform fallback is allowed.

“Unavailable” applies to one model + key + region combination, never to a whole provider. A throttled key doesn’t take its provider offline; that combination is skipped and retried once it recovers.

Tip

For optimal high availability, add two provider keys, one on OpenAI and one on Gemini. Failover can only route to keys you’ve added; with a single provider key there’s little to fall back to before the platform key.

Model pairs

Each tier has a matched peer on the other provider. When Foldspace crosses providers, it uses the requested model’s peer at the same tier.

Tier	Google Gemini	OpenAI peer
Lite	Gemini 3.1 Flash Lite	GPT-5.6 Luna
Standard	Gemini 3.5 Flash	GPT-5.6 Terra
Pro	Gemini 3.1 Pro Preview	GPT-5.6 Sol

Note

For streaming replies, failover only happens before the first tokens reach the user. Once tokens start streaming, that option is committed.

When a model is already unavailable

A model, key, and region combination that was recently marked unavailable is skipped, and the request goes straight to the next healthy option:

• One of your keys is down: the request continues on another of your keys, then a different provider or model.
• All your keys are exhausted: the Foldspace platform key handles the turn, when platform fallback is allowed.
• Nothing healthy is left: the turn fails, and the user sees a brief technical-difficulty message.

Failover events

Every failover and failback is recorded in Event Explorer as one of four routing events — see Failover events for what each one fires on and the properties it carries. Open it to review each event and understand:

• Reason — what made the primary unavailable, and why traffic failed back.
• Timing — when failover happened, and how long the cooldown ran before failback.
• Customer impact — which requests were affected, and whether the end user saw any disruption.

Related

• Failover events: the four routing events, their failure reasons, and common investigations.
• Token Quotas: cap token spend per agent, user, and tier.
• AI Provider Keys: add and rotate the provider keys failover routes across.