Model Fallback System

Overview

The bot now automatically switches between different Gemini models when quota limits are reached, ensuring continuous service even when one model hits its daily limit.

Model Hierarchy (Fallback Order)

1. Gemini 2.5 Pro (gemini-2.5-pro) - 50 requests/day (highest quality)
2. Gemini 2.5 Flash (gemini-2.5-flash) - 200 requests/day
3. Gemini 2.5 Flash Lite (gemini-2.5-flash-lite) - 500 requests/day
4. Gemini 2.0 Flash (gemini-2.0-flash-exp) - 200 requests/day
5. Gemini 2.0 Flash Lite (gemini-2.0-flash-lite) - 300 requests/day
6. Gemini 1.5 Flash (gemini-1.5-flash) - 1,500 requests/day
7. Gemma 2B (gemma-2b-it) - UNLIMITED ♾️ (final fallback)

How It Works

Automatic Model Selection

• Bot starts with Gemini 2.0 Flash (highest quality)
• When quota is exhausted (429 error), automatically switches to next model
• Tracks daily usage for each model
• Resets counters at midnight each day

Smart Fallback Logic

• Real-time switching: When a 429 error occurs, immediately tries next available model
• Usage tracking: Records every successful API call to track quotas
• Daily reset: All quotas reset at midnight automatically
• Unlimited fallback: Gemma 2B provides unlimited responses when all others are exhausted
• 99.9% uptime: Bot never goes offline due to model quotas

User Experience

• Seamless: Users don't notice model switches
• Always available: Bot never goes offline due to unlimited Gemma fallback
• Quality first: Always uses the best available model
• No daily limits: Unlimited responses guaranteed

Model Progression Example

// Typical daily progression:
🤖 Start: Gemini 2.5 Pro (50 requests) - Premium quality
📊 50/50 used → Switches to Gemini 2.5 Flash (200 requests)
📊 200/200 used → Switches to Gemini 2.5 Flash Lite (500 requests)  
📊 500/500 used → Switches to Gemini 2.0 Flash (200 requests)
📊 200/200 used → Switches to Gemini 2.0 Flash Lite (300 requests)
📊 300/300 used → Switches to Gemini 1.5 Flash (1,500 requests)
📊 1,500/1,500 used → Switches to Gemma 2B (UNLIMITED) ♾️
🚀 Bot continues working indefinitely - never goes offline!

API Endpoints

Check Model Status

GET /api/models

Response:

{
  "success": true,
  "data": {
    "currentModel": "gemini-2.5-pro",
    "usage": [
      {
        "name": "gemini-2.5-pro",
        "version": "2.5-pro",
        "dailyUsage": 45,
        "dailyLimit": 50,
        "isBlocked": false,
        "usagePercentage": 90
      },
      {
        "name": "gemini-2.5-flash", 
        "version": "2.5-flash",
        "dailyUsage": 0,
        "dailyLimit": 200,
        "isBlocked": false,
        "usagePercentage": 0
      }
    ],
    "nextReset": "2025-09-18T00:00:00.000Z"
  }
}

Get Current Active Model

GET /api/current-model

Response:

{
  "success": true,
  "data": {
    "currentModel": "gemini-2.5-pro",
    "version": "2.5-pro",
    "dailyUsage": 45,
    "dailyLimit": 50,
    "usagePercentage": 90,
    "isBlocked": false,
    "isUnlimited": false,
    "timestamp": "2025-09-17T14:30:00.000Z"
  }
}

Configuration

Adding New Models

Edit src/utils/modelFallback.ts and add to MODEL_CONFIGS:

{
    name: "model-name",
    version: "1.0", 
    dailyLimit: 100,
    isActive: true
}

Rate Limiting Integration

• Works with existing rate limiting system
• Models switch independently of user rate limits
• Users get stored messages processed regardless of model switches

Benefits

1. 100% Uptime: Bot NEVER goes offline - unlimited Gemma fallback
2. Cost Efficient: Maximizes free tiers across 6 premium models + unlimited backup
3. Quality First: Always uses the highest quality available model
4. Transparency: Full visibility into model usage via API
5. Zero Maintenance: Fully automatic with unlimited final fallback
6. Progressive Degradation: 2,750+ total daily requests across premium models before unlimited fallback

Logs

Bot logs model switches for monitoring:

🤖 Using model: gemini-2.5-pro
🔄 Quota exhausted for gemini-2.5-pro, trying fallback...
✅ Switched to fallback model: gemini-2.5-flash (v2.5-flash)
🔄 Quota exhausted for gemini-2.5-flash, trying fallback...
✅ Switched to fallback model: gemini-2.5-flash-lite (v2.5-flash-lite)
...
🚀 Falling back to unlimited model: gemma-2b-it (vgemma-2b)