Group failover

A routing group is a set of upstream channels. An ordinary API key names one primary group and, optionally, fallback groups in priority order. When the primary group cannot serve a request, the gateway continues down that list instead of returning an error to your client.

Configure the chain in API Keys when you create or edit a key. Order matters, and the console lets you move entries up and down.

When the request moves to the next group

• The group has no channel for the requested model.
• The group is at its rate limit for your account.
• Every channel priority inside the group has been tried and still returned a retryable error.

A group exhausts its own channel priorities before the next group is tried, so a fallback is a route change, not an extra retry of the same upstream.

When it does not

Failover covers route and connection problems only. The request stops immediately on:

• client errors — malformed JSON, an invalid parameter, context length exceeded;
• a cancelled client connection;
• a request pinned to one specific channel;
• a streamed response that has already sent real body bytes to your client. Heartbeats alone do not close the door, but once content has been written the request is never replayed on another route.

Billing

After a switch, the request is billed with the multiplier of the group that served it, not of the primary group. The group that served is recorded in the consume log.

Campaign groups require a fallback

Limited-time routes are temporary by design. When a key’s primary group is a campaign route, saving the key requires at least one concrete fallback group, so the key keeps working once that route ends.

Smart API Keys

A Smart API Key already walks every group your account can use, ordered by its routing strategy, so it does not take a manual fallback list.