How Fallback Works

Styrr maintains an ordered list of models. On each call():

1. Try the first model in the chain.
2. If it returns a successful response → return immediately.
3. If it returns a fallback-eligible status code → try the next model.
4. If all models fail → throw or invoke onAllFailed.

// Visual flow:
model_A → 429? → model_B → 404? → model_C → success ✓

Fallback-Eligible Status Codes

Code	Meaning	Fallback?
200	Success	No
429	Rate limited	Yes
404	Model removed	Yes
402	Insufficient credits	Yes
500-599	Server error	Yes
401	Auth failure	No (fail fast)

Hooks

const router = new StyrRouter({
  apiKey: process.env.OPENROUTER_API_KEY,
  models: [model_a, model_b, model_c],

  // Called on each fallback
  onFallback: (model, error, nextModel) => {
    console.warn(`${model} failed: ${error.message} → trying ${nextModel}`);
  },

  // Called when all models are exhausted
  onAllFailed: (errors) => {
    console.error('All models failed', errors);
    // Optionally return a fallback response
  },
});

Strategies

Paid First, Free Fallback

const router = new StyrRouter({
  apiKey: process.env.OPENROUTER_API_KEY,
  models: [
    { id: 'openai/gpt-4o' },                    // Best quality, costs $
    { id: 'nvidia/nemotron-3-ultra-550b:free' }, // Free fallback
    { id: 'google/gemma-4-31b-it:free' },         // Second free fallback
  ],
  onFallback: (model, err, next) => {
    // Log: "gpt-4o rate limited → switching to free"
  },
});

Free Only (Zero Cost)

const router = new StyrRouter({
  models: [
    { id: 'nvidia/nemotron-3-ultra-550b:free' },
    { id: 'google/gemma-4-31b-it:free' },
    { id: 'meta-llama/llama-3.3-70b-instruct:free' },
  ],
});