Failover Without False Confidence
CC Switch's failover feature addresses a specific failure: a request has entered the local proxy, but the provider currently chosen for that application cannot complete it. This chapter separates that symptom from the possible causes, follows the queue and circuit-breaker decisions that come next, and shows what retrying can change. The practical outcome is a way to configure and interpret failover without mistaking a green health badge for an upstream guarantee or a successful retry for an unchanged workflow.
A failed request has more than one cause
Failover begins with prerequisites that are easy to overlook. The local proxy must be running, takeover must be enabled for the application, a queue must contain candidate providers, and automatic failover must be switched on. Without those conditions, CC Switch has no request-plane authority to move a request to another provider; depending on which condition is missing, the client or proxy may simply report an error rather than retry. Several provider cards in the database are not, by themselves, a failover system.
When those conditions hold, the first question is eligibility. CC Switch's provider router reads the configured failover queue in priority order. The queue is a policy: its first entry is the preferred candidate, the following entries are fallbacks, and providers outside the queue are not automatically part of that sequence. The router checks whether each candidate is present and whether its per-provider circuit is available. It then gives the request an ordered set of candidates rather than an undifferentiated pool.
This separation matters because queue order and health are different decisions. A provider may be first in the queue but currently skipped because its circuit is open. A provider may be healthy but never chosen because it appears later in the queue. A provider may be marked as a current target in the interface while the next routed request is governed by the queue. Reading the queue and the circuit state together is more informative than reading any one status label.
The router's circuit key combines the application and provider identity. That prevents a failure observed while routing Claude from automatically becoming a failure for the same provider entry under another application's request rules. It also allows each application to have its own proxy configuration and retry behavior. This is a necessary separation because the clients have different request durations, protocols, and likely failure patterns. A policy tuned for a long Claude stream should not silently become the policy for a short Gemini request.
The router also filters candidates that are not safe to retry. The clearest example is an official Codex provider bound to a particular ChatGPT account. A request arriving from a Codex session carries authentication context associated with the account that session loaded. Reusing that request against a different account-bound provider could cross an identity boundary even if the transport-level retry succeeded. CC Switch therefore keeps such official account-bound cards out of generic failover. This is not a lack of redundancy by accident; it is a decision that account continuity outranks blind availability.
Once a candidate is eligible, the proxy obtains permission from that provider's circuit breaker and attempts the request. A successful response records success. A failed attempt records failure, updates the circuit's counters, and updates persistent provider-health information. If retry policy allows another candidate, the router advances through the queue.