How FreeLLMAPI Health Checker Determines API Key Status

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

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.

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.

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

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.

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.

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

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 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 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. 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), Google Gemini (server/src/providers/google.ts), Cohere (server/src/providers/cohere.ts), and Cloudflare AI (server/src/providers/cloudflare.ts). Each provider defines its own validation endpoint and success criteria.

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