Model Failover

SwarmClaw supports automatic credential failover to keep agents running when a provider returns errors.

How It Works

When an agent makes a request to an LLM provider and receives one of these HTTP status codes:

  • 401 — Unauthorized (invalid or expired API key)
  • 429 — Rate limited (too many requests)
  • 500 / 502 / 503 — Server errors

SwarmClaw automatically retries the request with the next credential in the agent's fallback chain.

Configuration

Setting Up Fallback Credentials

  1. Open the Agent Editor for the agent you want to configure
  2. Under Fallback Credentials, you'll see available credentials for the agent's provider
  3. Toggle on the credentials you want as fallbacks
  4. The order determines retry priority — first in the list is tried first

Requirements

  • The agent must have a primary credential assigned
  • Fallback credentials must be for the same provider type (e.g., all OpenAI keys, or all Anthropic keys)
  • At least one fallback credential must be configured for failover to activate

Retry Behavior

  1. Agent sends request with primary credential
  2. Provider returns a retryable error (401, 429, 500, 502, 503)
  3. SwarmClaw decrypts the first fallback credential
  4. Request is retried with the fallback credential
  5. If that also fails with a retryable error, the next fallback is tried
  6. If all credentials fail, the error is returned to the user

A metadata event is sent to the chat stream indicating when a failover occurs, so users can see which credential succeeded.

Use Cases

  • Rate limit management — Spread load across multiple API keys
  • Key rotation — Seamlessly switch to new keys without downtime
  • Multi-account — Use personal and team keys as fallbacks
  • Provider resilience — Handle temporary provider outages gracefully