# How FreeLLMAPI Health Checker Determines API Key Status

> Discover how the FreeLLMAPI health checker validates API keys every 5 minutes using decryption and provider-specific methods, ensuring optimal performance and auto-disabling invalid keys.

- Repository: [Tashfeen/freellmapi](https://github.com/tashfeenahmed/freellmapi)
- Tags: how-to-guide
- Published: 2026-06-23

---

**The FreeLLMAPI health checker validates API keys every 5 minutes by decrypting stored credentials and executing provider-specific `validateKey` methods that perform lightweight HTTP requests, marking keys as `healthy`, `invalid`, or `error` while auto-disabling keys after three consecutive failures.**

The FreeLLMAPI health checker is a critical subsystem in the `tashfeenahmed/freellmapi` repository that ensures only valid API keys remain active for load balancing across language model providers. Implemented in [`server/src/services/health.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/health.ts), this service periodically evaluates each enabled key by orchestrating database lookups, cryptographic decryption, and provider-specific validation logic to determine key viability.

## How the Health Checker Evaluates API Keys

### Fetching and Decrypting Key Records

Every validation cycle begins by querying the SQLite `api_keys` table to retrieve the key record and resolve the appropriate provider instance. The checker uses the stored platform identifier and optional custom base URL to instantiate the correct provider class.

```typescript
const row = db.prepare('SELECT * FROM api_keys WHERE id = ?').get(keyId);
const provider = resolveProvider(row.platform as Platform, row.base_url);

```

Before validation occurs, the system decrypts the **stored API key** using the initialization vector and authentication tag saved alongside the encrypted credential.

```typescript
const apiKey = decrypt(row.encrypted_key, row.iv, row.auth_tag);

```

### Provider-Specific Validation Logic

Each provider implements a `validateKey` method that performs a lightweight HTTP request—typically **GET /v1/models**—to verify credential validity without consuming significant quota. For OpenAI-compatible providers, the implementation returns `true` only when the response status is neither **401 Unauthorized** nor **403 Forbidden**.

```typescript
const res = await this.fetchWithTimeout(url, { method: 'GET', headers: this.authHeader(apiKey) }, 30000);
return res.status !== 401 && res.status !== 403;

```

This validation logic resides in [`server/src/providers/openai-compat.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/providers/openai-compat.ts), with specialized implementations also available for Google Gemini, Cohere, and Cloudflare AI in their respective provider files.

### Status Interpretation and Auto-Disable Logic

The health checker maps the boolean `validateKey` result to discrete status values and applies automatic remediation policies. A return value of `true` sets the status to **`healthy`**, while `false` marks the key as **`invalid`** and increments a per-key failure counter.

When the **consecutive failure counter reaches three**, the system automatically disables the key by setting `enabled = 0` in the database, preventing further routing of requests to compromised or expired credentials.

```typescript
const status: KeyStatus = isValid ? 'healthy' : 'invalid';
if (!isValid) {
    const count = (failureCount.get(keyId) ?? 0) + 1;
    failureCount.set(keyId, count);
    if (count >= CONSECUTIVE_FAILURES_TO_DISABLE) {
        db.prepare('UPDATE api_keys SET enabled = 0 WHERE id = ?').run(keyId);
    }
}

```

**Transport errors**—such as DNS failures, timeouts, or connection resets—are caught separately and assigned the **`error`** status. Importantly, these network-level failures do not increment the failure counter, ensuring temporary connectivity issues do not trigger unnecessary key disabling.

```typescript
console.error(`[Health] Key ${keyId} transport error:`, err.message);
db.prepare("UPDATE api_keys SET status = ?, last_checked_at = datetime('now') WHERE id = ?")
    .run('error', keyId);

```

## Scheduling and Execution

The health checker runs on a fixed interval defined by the constant `CHECK_INTERVAL_MS = 5 * 60 * 1000`, executing every **5 minutes**. The `startHealthChecker()` function initializes this timer when the server process boots, ensuring continuous monitoring without manual intervention.

```typescript
// Located in server/src/services/health.ts, lines 75-81
startHealthChecker(); // Registers the 5-minute interval

```

## Running Health Checks Manually

While the system runs automatically, administrators can trigger individual key validations using the exported `checkKeyHealth` function. This is useful for debugging or verifying newly added keys before they enter the rotation.

```typescript
import { checkKeyHealth } from './server/src/services/health.js';

async function validateSpecificKey() {
  const status = await checkKeyHealth(42); // Validates key ID 42
  console.log(`Key 42 status: ${status}`);
}

```

## Summary

- The FreeLLMAPI health checker operates from [`server/src/services/health.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/health.ts) and validates keys every 5 minutes via `startHealthChecker()`.
- Each validation decrypts the stored credential using `decrypt()` and invokes the provider's `validateKey` method, typically checking **GET /v1/models**.
- Valid keys receive **`healthy`** status; invalid keys receive **`invalid`** status and increment a failure counter that triggers auto-disable after three consecutive failures.
- Transport errors receive **`error`** status without incrementing the failure counter, preventing temporary network issues from disabling valid keys.
- Provider-specific implementations in [`server/src/providers/openai-compat.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/providers/openai-compat.ts) and related files handle platform-specific validation logic.

## Frequently Asked Questions

### How often does FreeLLMAPI check API key health?

The health checker runs automatically every **5 minutes** (300,000 milliseconds) as defined by the `CHECK_INTERVAL_MS` constant in [`server/src/services/health.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/health.ts). This interval balances timely detection of invalid keys with minimal API quota consumption.

### What happens when an API key fails validation?

When a key fails validation, the system marks it as **`invalid`** and increments an internal failure counter. Upon reaching **three consecutive failures**, the key is automatically disabled via an `UPDATE` to the `enabled` column in the `api_keys` table, removing it from the load balancing pool.

### Does a network error disable an API key in FreeLLMAPI?

No. Transport errors such as DNS failures, timeouts, or connection issues set the key status to **`error`** but explicitly **do not** increment the failure counter. This design prevents temporary network glitches from incorrectly disabling otherwise valid API keys.

### Which providers support health checking in FreeLLMAPI?

All providers implementing the `validateKey` method support health checking, including OpenAI-compatible services ([`server/src/providers/openai-compat.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/providers/openai-compat.ts)), Google Gemini ([`server/src/providers/google.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/providers/google.ts)), Cohere ([`server/src/providers/cohere.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/providers/cohere.ts)), and Cloudflare AI ([`server/src/providers/cloudflare.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/providers/cloudflare.ts)). Each provider defines its own validation endpoint and success criteria.