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

> Easily configure OmniRoute provider-specific circuit breaker thresholds and reset timeouts using environment variables. Customize OAuth, API-Key, and local provider settings without code changes.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: how-to-guide
- Published: 2026-08-11

---

**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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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

```dotenv

# .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

```typescript
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

```typescript
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/config/constants.ts) — defines base values and environment bindings
2. **`buildProviderProfile()`** in [`open-sse/services/accountFallback.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/config/constants.ts) | Defines `PROVIDER_PROFILES` and environment variable mappings |
| [`open-sse/services/accountFallback.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/accountFallback.ts) | Implements `buildProviderProfile()` and `getProviderProfile()` |
| [`src/lib/resilience/settings.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/resilience/settings.ts) | Consumes profiles for connection resilience configuration |
| [`tests/unit/error-classification.test.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/config/constants.ts) reads them at process startup, so changes require a restart to take effect.