How to Configure Provider-Specific Circuit Breaker Thresholds and Reset Timeouts in OmniRoute

OmniRoute allows per-provider circuit breaker configuration through environment variables that override default thresholds and reset timeouts for OAuth, API-Key, and local provider categories without code changes.

OmniRoute protects downstream providers from cascading failures with a sophisticated circuit-breaker mechanism that operates on a per-provider basis. Understanding how to configure provider-specific circuit breaker thresholds and reset timeouts gives operators fine-grained control over resilience behavior across different provider types.

Where Circuit Breaker Configuration Lives

The default values and environment variable mappings reside in open-sse/config/constants.ts. This file defines the PROVIDER_PROFILES object that categorizes providers into three groups, each with distinct failure sensitivity and recovery timing.

Default Thresholds and Timeouts by Provider Category

Category	Default Failure Threshold	Default Reset Timeout
OAuth	8 failures	60,000 ms (1 minute)
API-Key	12 failures	30,000 ms (30 seconds)
Local	2 failures	15,000 ms (15 seconds)

OAuth providers tolerate fewer failures but recover more slowly, reflecting their typically higher latency and rate-limit sensitivity. Local providers trip immediately on minimal failures since they represent in-process components where errors indicate deep system issues.

Environment Variable Overrides

All defaults are read through the envInt() helper, enabling runtime configuration without recompilation.

Available Environment Variables

• OMNIROUTE_CIRCUIT_BREAKER_OAUTH_THRESHOLD
• OMNIROUTE_CIRCUIT_BREAKER_OAUTH_RESET_MS
• OMNIROUTE_CIRCUIT_BREAKER_API_KEY_THRESHOLD
• OMNIROUTE_CIRCUIT_BREAKER_API_KEY_RESET_MS
• OMNIROUTE_CIRCUIT_BREAKER_LOCAL_THRESHOLD
• OMNIROUTE_CIRCUIT_BREAKER_LOCAL_RESET_MS

Practical Configuration Examples

Override OAuth Circuit Breaker via Environment File

# .env

OMNIROUTE_CIRCUIT_BREAKER_OAUTH_THRESHOLD=5
OMNIROUTE_CIRCUIT_BREAKER_OAUTH_RESET_MS=120000

This makes OAuth providers more conservative—opening after 5 failures and staying open for 2 minutes before probe attempts resume.

Inspect Effective Profile at Runtime

import { getProviderProfile } from '@/open-sse/services/accountFallback';

const claudeProfile = getProviderProfile('claude');
console.log(claudeProfile.circuitBreakerThreshold); // 5 (overridden)
console.log(claudeProfile.circuitBreakerReset);    // 120000

const openaiProfile = getProviderProfile('openai');
console.log(openaiProfile.circuitBreakerThreshold); // 12 (default)
console.log(openaiProfile.circuitBreakerReset);    // 30000 (default)

Configure Custom Thresholds in Test Suites

process.env.OMNIROUTE_CIRCUIT_BREAKER_API_KEY_THRESHOLD = '20';
process.env.OMNIROUTE_CIRCUIT_BREAKER_API_KEY_RESET_MS = '60000';

import { getProviderProfile } from '@/open-sse/services/accountFallback';
const profile = getProviderProfile('openai');

expect(profile.circuitBreakerThreshold).toBe(20);
expect(profile.circuitBreakerReset).toBe(60000);

How Configuration Flows Through the System

The resolution chain follows three layers:

1. PROVIDER_PROFILES in open-sse/config/constants.ts — defines base values and environment bindings
2. buildProviderProfile() in open-sse/services/accountFallback.ts — constructs the ProviderProfile with circuitBreakerThreshold and circuitBreakerReset fields
3. getProviderProfile() — the public interface consumed by routing, fallback, and resilience modules throughout the codebase

The getProviderProfile() function is the authoritative source for per-provider settings. According to the OmniRoute source code, this function queries the profile and extracts category-appropriate values based on provider authentication type.

Consumption in Resilience Layer

The src/lib/resilience/settings.ts module consumes PROVIDER_PROFILES to configure connection-level back-off and cooldown logic, ensuring circuit breaker settings integrate with broader retry and timeout strategies.

Key Source Files

File	Purpose
open-sse/config/constants.ts	Defines PROVIDER_PROFILES and environment variable mappings
open-sse/services/accountFallback.ts	Implements buildProviderProfile() and getProviderProfile()
src/lib/resilience/settings.ts	Consumes profiles for connection resilience configuration
tests/unit/error-classification.test.ts	Validates profile exposure to the system

Summary

• Environment-driven configuration — all circuit breaker thresholds and reset timeouts are overrideable via environment variables without recompiling
• Category-based defaults — OAuth, API-Key, and local providers have distinct sensitivity profiles optimized for their failure modes
• getProviderProfile() as the interface — uniformly retrieves effective settings across routing and resilience modules
• PROVIDER_PROFILES as the source — single location for default values and environment bindings in open-sse/config/constants.ts

Frequently Asked Questions

How do I make a specific provider more sensitive to failures?

Set the appropriate THRESHOLD environment variable for its category. For an OAuth provider like Claude, use OMNIROUTE_CIRCUIT_BREAKER_OAUTH_THRESHOLD=3 to trip after just 3 consecutive failures instead of the default 8.

Can different providers of the same category have different thresholds?

Not directly through environment variables—thresholds apply per category. To customize individual providers, you would need to modify the buildProviderProfile() logic in open-sse/services/accountFallback.ts to accept provider-specific overrides.

What happens when the reset timeout expires?

After circuitBreakerReset milliseconds, OmniRoute allows a single probe request through. If it succeeds, the circuit closes and normal operation resumes. If it fails, the circuit reopens and the timeout resets.

Where should I set these environment variables in production?

Define them in your container orchestration configuration (Kubernetes ConfigMap/Secret, Docker Compose environment, or systemd service files). The envInt() helper in open-sse/config/constants.ts reads them at process startup, so changes require a restart to take effect.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}