OpenRouter emergency fallback
The last-resort continuity layer - used only after a verified primary failure for a required model path, gated behind explicit policy, and audited on every use. Never routine arbitration.
OpenRouter is Zumik's emergency exit, not an execution profile. It is a single last-resort continuity layer that fires only when a primary provider has a verified failure for a required model path. It never participates in normal routing, price arbitration, or load balancing, and it is off unless an operator explicitly turns it on.
The execution mode is reported on the Agent-Execution-Mode response header: live (the primary
gateway served it), openrouter_fallback (the emergency path served it), or placeholder (no gateway
configured, or every path failed).
When it fires
It is narrow by design. All of these have to be true:
A verified primary failure
The managed gateway path returned an upstream failure for a required model path - not a slow response, not a price signal, an actual failure.
The operator has enabled it
OPENROUTER_FALLBACK_ENABLED is set. With it off, a primary failure degrades straight to the
placeholder. The fallback ships disabled.
Project policy permits brokered execution
The project's regional policy data boundary is not strict and not
no_openrouter. A project with no policy configured falls under the operator-level opt-in.
If any condition fails, Zumik returns a clear degraded response or rejection. It never silently brokers a request through a third party to avoid an error.
What it is never for
OpenRouter is never used for routine routing or price arbitration. Cheaper-elsewhere is not a reason to use it. The only trigger is a verified outage on a required model path, and even then only when policy allows it.
- BYOK traffic never falls back to OpenRouter. The customer's key is their explicit choice, so a BYOK failure degrades to the placeholder, not a broker. See BYOK.
- A
strictorno_openrouterdata boundary disables it for that project regardless of the operator-level setting. - It is not a coverage strategy. Broad model coverage comes from the managed-provider profile through Bifrost's 23+ backends and automatic multi-provider failover, which happens before this layer is ever considered.
Every use is audited
When the fallback fires, Zumik records the exception so it is never invisible. An audit log entry with
action execution.openrouter_fallback captures which upstream model path failed and the reason, and
the policy that permitted the exception is implicit in the fact that the request was allowed through at
all.
{
"object": "audit_log_entry",
"action": "execution.openrouter_fallback",
"actor": "system",
"target": "claude-3-7-sonnet",
"metadata": { "failed_reason": "upstream provider 503" }
}This is the same audit surface the BYOC clusters API and credential operations write to, so an emergency fallback is reviewable next to every other accountable action.
Where it sits
The overview lays out the full escalation order. The short version: the broker exhausts the managed path - including Bifrost's own multi-provider failover - before it reaches here, and this layer exists only so a verified outage on a required model path produces continuity rather than a hard failure, for the projects whose policy allows it.
Hybrid profile
Managed providers for broad coverage and overflow, with BYOC hot lanes carrying the few model paths concentrated enough to justify dedicated infrastructure. The common shape for coding-agent platforms.
OpenAI
OpenAI through Zumik - automatic prompt caching at a 50% read discount, the Batch API at 50% off, flex/default/scale service tiers, response retrieval and background mode, and when the broker routes here.