Provider Fallbacks & Failover Logic

Provider fallbacks and failover logic in Aimogen are designed to make AI execution predictable and transparent, not automatic or hidden. Aimogen will never silently switch providers or models unless you explicitly configure it to do so. This document explains exactly how fallback behavior works, what is automatic, what is optional, and what never happens.

---

Core Principle #

Aimogen does not guess.

If a provider or model fails, Aimogen reports the failure clearly. Any fallback behavior happens only when it is explicitly defined or implied by your configuration.

There is no global “auto-switch to another provider” feature that runs behind your back.

---

What Counts as a Failure #

A provider execution is considered failed when one of the following occurs:

• API key is missing or invalid
• Provider returns an authentication error
• Provider returns a rate-limit error
• Provider times out or is unreachable
• Provider returns an invalid or empty response
• Model does not support the requested execution type

Failures are logged immediately and surfaced in diagnostics.

---

Default Behavior (No Fallbacks Configured) #

If no fallback logic is configured:

• The execution fails
• The error is logged
• The feature stops gracefully
• No other provider or model is tried
• No hidden retries occur

This is intentional. Silent provider switching would hide problems and make cost and output unpredictable.

---

Where Fallbacks Can Exist #

Fallbacks in Aimogen can exist only in three controlled places:

1. Feature-level configuration
2. Workflow / OmniBlock execution chains
3. Provider key rotation (same provider only)

There is no global provider failover switch.

---

1. Feature-Level Provider Fallbacks #

Some features allow you to define primary and secondary providers or models.

Example:

• Primary model: OpenAI GPT-style model
• Secondary model: Claude or Gemini

If the primary execution fails:

• Aimogen attempts the secondary model
• The fallback attempt is logged
• If the fallback fails, execution stops

This must be explicitly configured per feature. If you don’t define it, no fallback occurs.

---

2. Workflow / OmniBlock Failover #

Workflows provide the most advanced and explicit failover control.

In workflows:

• Each step can use a different provider or model
• You can branch execution based on success or failure
• You can retry with a different provider manually
• You can stop execution intentionally on failure

This is intentional failover, not automatic failover.

Example patterns:

• Try a fast model first, retry with a stronger one
• Try a cheap model, escalate only if output fails validation
• Stop workflow entirely if a critical provider fails

Workflows give full control, but require explicit logic.

---

3. API Key Rotation (Same Provider Only) #

When multiple API keys are entered for the same provider, Aimogen may rotate keys only within that provider.

This is not provider failover.

Example:

• Multiple OpenAI keys
• One key hits a rate limit
• Aimogen tries the next OpenAI key

This never switches:

• Provider
• Model family
• Pricing tier

It exists only to reduce temporary rate-limit interruptions.

---

What Aimogen Will Never Do #

Aimogen will never:

• Switch providers automatically without configuration
• Switch from one vendor to another silently
• Retry indefinitely
• Mask provider errors
• Fallback to a cheaper or worse model without permission

Every execution path is deterministic.

---

How Fallbacks Are Logged #

When a fallback occurs:

• The original failure is logged
• The fallback attempt is logged
• The final execution result is logged

You can see:

• Which provider failed
• Why it failed
• Which provider (if any) was tried next
• Whether the fallback succeeded

Nothing is hidden.

---

Recommended Fallback Strategies #

For production environments:

• Do not rely on implicit fallback
• Use workflows for critical reliability
• Define explicit secondary providers where needed
• Keep real-time chat on fast, reliable models
• Keep bulk jobs on predictable, cost-controlled models

Failover should be designed, not assumed.

---

When Not to Use Fallbacks #

Avoid provider fallbacks when:

• Output consistency is critical
• Cost predictability matters
• You need reproducible results
• You are debugging prompts or models

Silent variability is worse than visible failure in these cases.

---

Summary #

• Aimogen does not auto-failover by default
• Failures are explicit and logged
• Fallbacks must be configured intentionally
• Workflows provide full failover control
• API key rotation is provider-local only
• No silent provider or model switching exists

This design ensures that Aimogen remains predictable, debuggable, and production-safe, even when working with multiple AI providers.