| name | hermes-model-fallback |
| description | Handles AI model failures (HTTP 429, HTTP 503, Timeout) by automatically switching to a backup model without freezing or crashing. Use this skill whenever you need resilient multi-model API calls, rate-limit protection, or automatic failover between different AI providers (Gemini, OpenAI, Claude, Mistral, etc.). Trigger when the user mentions "fallback", "model switch", "rate limit", "429", "503", "timeout retry", "multi-model", or wants their agent to be fault-tolerant against API errors.
|
Hermes Model Fallback Skill
Automatically switches AI models when HTTP 429 / 503 / Timeout errors occur.
Retries the same model up to 2 times, then moves to the next model in the list.
Quick Start (5 minutes)
Step 1 — Configure your models
Open scripts/config.json and fill in your API keys and preferred model order:
{
"models": [
{
"provider": "gemini",
"model": "gemini-1.5-pro",
"api_key": "YOUR_GEMINI_KEY"
},
{
"provider": "openai",
"model": "gpt-4o",
"api_key": "YOUR_OPENAI_KEY"
},
{
"provider": "claude",
"model": "claude-3-5-sonnet-20241022",
"api_key": "YOUR_ANTHROPIC_KEY"
}
],
"retry_limit": 2,
"timeout_seconds": 30
}
✅ You only need to fill in the providers you actually use.
✅ The order in the list = the fallback order (first = primary).
Step 2 — Use the Python version
from scripts.fallback_client import FallbackClient
client = FallbackClient("scripts/config.json")
response = client.chat("Tell me a joke about robots.")
print(response)
Step 3 — Use the JavaScript version
const { FallbackClient } = require('./scripts/fallbackClient');
const client = new FallbackClient('./scripts/config.json');
client.chat("Tell me a joke about robots.").then(console.log);
How Fallback Works
User Request
│
▼
[Model 1 - Primary]
├── ✅ Success → return response
├── ❌ 429/503/Timeout → retry (attempt 2)
│ ├── ✅ Success → return response
│ └── ❌ Still failing → retry (attempt 3 = final)
│ ├── ✅ Success → return response
│ └── ❌ Still failing ──────────────────┐
│ ▼
│ [Model 2 - Fallback #1]
│ ├── ✅ Success → return
│ └── ❌ Failing (3x) ──┐
│ ▼
│ [Model 3 - Fallback #2]
│ ├── ✅ Success
│ └── ❌ All failed → raise error
Retry logic: Each model gets 2 retries (3 total attempts) before switching.
Errors handled: HTTP 429, HTTP 503, Timeout, Connection Error.
Other errors (e.g. 401 Unauthorized, bad prompt) → fail immediately, no retry.
Supported Providers
Want to add a new provider? See references/add-provider.md.
Files in This Skill
hermes-model-fallback/
├── SKILL.md ← You are here
├── scripts/
│ ├── config.json ← Your model list & API keys
│ ├── fallback_client.py ← Python client (ready to use)
│ └── fallbackClient.js ← JavaScript client (ready to use)
└── references/
├── add-provider.md ← How to add a new AI provider
└── troubleshooting.md ← Common errors & fixes
Tips
- Keep API keys safe: Use environment variables instead of hardcoding.
Set "api_key": "ENV:GEMINI_API_KEY" and the client reads from os.environ.
- Ollama (local model) requires no API key — great as a final offline fallback.
- Timeout default is 30 seconds. Lower it if you want faster switching.
- Read
references/troubleshooting.md if you hit unexpected errors.
