Skip to content

7.4 billion tokens per month. 34 free LLM providers. 635 free model endpoints. All behind one /v1 endpoint, plus any custom OpenAI-compatible endpoint. Smart routing, automatic failover, encrypted keys. Personal experimentation only.

TypeScript

fix(health): stop polling SerpSearch, Exa and Parallel keys with empty searches (#1599) (#1608)

Tashfeenb78a77403803
diff --git a/docs/BEATAPI-SERPSEARCH.md b/docs/BEATAPI-SERPSEARCH.md
index 741c2487..42d6db5d 100644
--- a/docs/BEATAPI-SERPSEARCH.md
+++ b/docs/BEATAPI-SERPSEARCH.md
@@ -36,6 +36,9 @@ Sources: [decision API](https://docs.beatapi.io/decisions),
- Key validation omits `query`. A valid key returns a missing-query HTTP 400
with quota headers, an invalid key returns 401. Both were live checked, and
the valid probe did not decrement quota. Unexpected responses are inconclusive.
+- That probe runs once per key, never on the 5-minute health schedule (#1599).
+ SerpSearch revoked a free account over empty searches every 5 minutes. After
+ the first check, real searches and "Check now" decide the key's status.
- The adapter follows the existing no-hits fallback policy and result limit.
It does not paginate automatically or consume extra credits to fill results.
diff --git a/server/src/__tests__/services/health-no-poll-provider.test.ts b/server/src/__tests__/services/health-no-poll-provider.test.ts
new file mode 100644
index 00000000..bc15c5ae
--- /dev/null
+++ b/server/src/__tests__/services/health-no-poll-provider.test.ts
@@ -0,0 +1,103 @@
+import { describe, it, expect, beforeAll, beforeEach, vi } from 'vitest';
+
+// #1599: SerpSearch revoked a free account over the empty search the health
+// pass sent every 5 minutes as its key check. A provider with
+// supportsKeyPolling === false gets one check per key, not one per pass.
+const validateKey = vi.fn();
+vi.mock('../../providers/index.js', async (importOriginal) => {
+ const actual = await importOriginal() as any;
+ return {
+ ...actual,
+ resolveProvider: () => ({ name: 'no-poll', supportsKeyPolling: false, validateKey }),
+ };
+});
+
+const { initDb, getDb } = await import('../../db/index.js');
+const { encrypt } = await import('../../lib/crypto.js');
+const { checkAllKeys, probeKeyValidity, NO_POLL_ERROR_REPROBE_MS } = await import('../../services/health.js');
+const { SerpSearchProvider } = await import('../../providers/serpsearch.js');
+const { ExaProvider } = await import('../../providers/exa.js');
+const { ParallelProvider } = await import('../../providers/parallel.js');
+
+describe('a provider that must not be polled (#1599)', () => {
+ let nextId = 9300;
+
+ beforeAll(() => {
+ process.env.ENCRYPTION_KEY = '0'.repeat(64);
+ initDb(':memory:');
+ });
+
+ beforeEach(() => {
+ getDb().prepare('DELETE FROM api_keys').run();
+ validateKey.mockReset();
+ validateKey.mockResolvedValue(true);
+ vi.spyOn(console, 'error').mockImplementation(() => {});
+ vi.spyOn(console, 'warn').mockImplementation(() => {});
+ vi.spyOn(console, 'log').mockImplementation(() => {});
+ });
+
+ /** ageMs null = never checked. */
+ function seedKey(status: string, ageMs: number | null): number {
+ const id = ++nextId;
+ const enc = encrypt(`no-poll-${id}`);
+ const checkedAt = ageMs === null ? null : new Date(Date.now() - ageMs).toISOString().replace('T', ' ').slice(0, 19);
+ getDb().prepare(`
+ INSERT INTO api_keys (id, platform, label, encrypted_key, iv, auth_tag, enabled, status, last_checked_at)
+ VALUES (?, 'serpsearch', ?, ?, ?, ?, 1, ?, ?)
+ `).run(id, `no-poll-${id}`, enc.encrypted, enc.iv, enc.authTag, status, checkedAt);
+ return id;
+ }
+
+ it('validates a new key once, then never again on the schedule', async () => {
+ const id = seedKey('unknown', null);
+
+ expect((await checkAllKeys()).checkedKeyIds).toEqual([id]);
+ expect(validateKey).toHaveBeenCalledOnce();
+
+ // The next scheduled pass and the forced post-wake pass both skip it.
+ expect((await checkAllKeys()).skippedKeyIds).toEqual([id]);
+ expect((await checkAllKeys({ force: true })).skippedKeyIds).toEqual([id]);
+ expect(validateKey).toHaveBeenCalledOnce();
+ });
+
+ it('leaves a healthy or invalid key alone however long ago it was checked', async () => {
+ const healthy = seedKey('healthy', 30 * 24 * 60 * 60 * 1000);
+ const invalid = seedKey('invalid', 30 * 24 * 60 * 60 * 1000);
+
+ const pass = await checkAllKeys({ force: true });
+
+ expect(pass.checkedKeyIds).toEqual([]);
+ expect(pass.skippedKeyIds.sort()).toEqual([healthy, invalid].sort());
+ expect(validateKey).not.toHaveBeenCalled();
+ });
+
+ it('re-asks about a key parked at error at most once per reprobe window', async () => {
+ const recent = seedKey('error', 10 * 60 * 1000);
+ const stale = seedKey('error', NO_POLL_ERROR_REPROBE_MS + 60 * 1000);
+
+ const pass = await checkAllKeys();
+
+ expect(pass.checkedKeyIds).toEqual([stale]);
+ expect(pass.skippedKeyIds).toEqual([recent]);
+ });
+
+ it('"Check all" still validates every key', async () => {
+ const id = seedKey('healthy', 60 * 1000);
+
+ expect((await checkAllKeys({ force: true, manual: true })).checkedKeyIds).toEqual([id]);
+ expect(validateKey).toHaveBeenCalledOnce();
+ });
+
+ it('the cooldown probe treats the key as inconclusive without probing', async () => {
+ const id = seedKey('healthy', 60 * 1000);
+
+ expect(await probeKeyValidity(id)).toBe('error');
+ expect(validateKey).not.toHaveBeenCalled();
+ });
+
+ it('is set for the providers whose key check is an empty search', () => {
+ expect(new SerpSearchProvider().supportsKeyPolling).toBe(false);
+ expect(new ExaProvider().supportsKeyPolling).toBe(false);
+ expect(new ParallelProvider().supportsKeyPolling).toBe(false);
+ });
+});
diff --git a/server/src/providers/base.ts b/server/src/providers/base.ts
index 4f35e875..5d479e8a 100644
--- a/server/src/providers/base.ts
+++ b/server/src/providers/base.ts
@@ -286,6 +286,19 @@ export abstract class BaseProvider {
return true;
}
+ /** Whether the scheduled health pass may re-validate this provider's keys
+ * every few minutes (#1599). A provider whose only key check is a malformed
+ * request to its billed endpoint (SerpSearch, Exa and keyed Parallel send a
+ * search with no query) returns false: to the provider those requests look
+ * like a script firing empty searches all day, and SerpSearch revoked a free
+ * account over them. The scheduled pass then validates such a key once, when
+ * it has never been checked, re-asks about a key parked at 'error' at most
+ * every NO_POLL_ERROR_REPROBE_MS, and leaves the rest to real traffic. The
+ * cooldown probe never validates it; "Check now" and "Check all" still do. */
+ get supportsKeyPolling(): boolean {
+ return true;
+ }
+
/**
* Turn a conventional 401/403 validation response into a diagnostic result.
* Providers still return a simple boolean when no useful error body exists,
diff --git a/server/src/providers/exa.ts b/server/src/providers/exa.ts
index 3590dd31..c3d994dd 100644
--- a/server/src/providers/exa.ts
+++ b/server/src/providers/exa.ts
@@ -5,14 +5,21 @@ import { SearchOnlyProvider } from './search-only.js';
export const EXA_BASE_URL = 'https://api.exa.ai';
// Exa (exa.ai): recurring monthly free credits. Exa has no free "who am I"
-// endpoint and the health checker validates every key every few minutes, so a
-// real search probe would burn the free credits within days. Instead the probe
+// endpoint, so a real search probe would spend credits. Instead the probe
// sends a search with no query: Exa authenticates first, so a bad key answers
// 401 while a good one fails body validation with a 400 and spends nothing.
+// Empty searches every few minutes look like abuse (#1599), so the health pass
+// sends this once per key, not on its schedule.
export class ExaProvider extends SearchOnlyProvider {
readonly platform: Platform = 'exa';
readonly name = 'Exa';
+ /** #1599: validation is an empty search, so the health pass checks a key
+ * once instead of every few minutes. */
+ override get supportsKeyPolling(): boolean {
+ return false;
+ }
+
async validateKey(apiKey: string): Promise<KeyValidationResult> {
return this.probe(`${EXA_BASE_URL}/search`, {
method: 'POST',
diff --git a/server/src/providers/parallel.ts b/server/src/providers/parallel.ts
index 65288abc..78c11ee4 100644
--- a/server/src/providers/parallel.ts
+++ b/server/src/providers/parallel.ts
@@ -20,6 +20,12 @@ export class ParallelProvider extends SearchOnlyProvider {
readonly name = 'Parallel';
keyless = true;
+ /** #1599: validation is an empty search, so the health pass checks a key
+ * once instead of every few minutes. */
+ override get supportsKeyPolling(): boolean {
+ return false;
+ }
+
async validateKey(apiKey: string): Promise<KeyValidationResult> {
if (isAnonymousCredential(apiKey)) {
return this.probe(PARALLEL_MCP_URL, {
diff --git a/server/src/providers/serpsearch.ts b/server/src/providers/serpsearch.ts
index 7cdfd551..60310fa0 100644
--- a/server/src/providers/serpsearch.ts
+++ b/server/src/providers/serpsearch.ts
@@ -7,10 +7,18 @@ export class SerpSearchProvider extends SearchOnlyProvider {
readonly platform = 'serpsearch' as const;
readonly name = 'SerpSearch';
+ /** #1599: validation is an empty search, so the health pass checks a key
+ * once instead of every few minutes. */
+ override get supportsKeyPolling(): boolean {
+ return false;
+ }
+
async validateKey(apiKey: string): Promise<KeyValidationResult> {
// Authentication runs before query validation: a valid key gets 400 with
// quota headers, an invalid key gets 401. No query means no credit spent.
// Live checked against both cases; do not turn this into a real search.
+ // Never poll this (#1599): SerpSearch revoked a free account over empty
+ // searches sent every 5 minutes. supportsKeyPolling keeps it to one per key.
const res = await this.fetchWithTimeout(`${SERPSEARCH_BASE_URL}/search`, {
method: 'GET', redirect: 'error', headers: { Authorization: `Bearer ${apiKey}` },
}, 10_000, { timeoutBounds: 'request' });
diff --git a/server/src/routes/health.ts b/server/src/routes/health.ts
index 0daea61e..3e19c279 100644
--- a/server/src/routes/health.ts
+++ b/server/src/routes/health.ts
@@ -74,9 +74,9 @@ healthRouter.post('/check/:keyId', async (req: Request, res: Response) => {
// Check all keys. Forced: someone pressed the button and wants an answer about
// every key now, so the scheduled pass' recency skip and provider spacing (#553)
-// don't apply.
+// don't apply, and providers that must not be polled (#1599) are checked too.
healthRouter.post('/check-all', async (_req: Request, res: Response) => {
- await checkAllKeys({ force: true });
+ await checkAllKeys({ force: true, manual: true });
res.json({ success: true });
});
diff --git a/server/src/services/health.ts b/server/src/services/health.ts
index 12a785b8..b1338f71 100644
--- a/server/src/services/health.ts
+++ b/server/src/services/health.ts
@@ -33,6 +33,11 @@ const CHECK_INTERVAL_JITTER = 0.2;
// short interval can never skip a whole pass' worth of keys.
export const RECENT_CHECK_SKIP_MS = 3.5 * 60 * 1000;
+// #1599: how often the scheduled pass re-asks about a key parked at 'error' on
+// a provider that must not be polled (supportsKeyPolling === false). Healthy
+// and invalid keys on those providers are never re-validated on a schedule.
+export const NO_POLL_ERROR_REPROBE_MS = 60 * 60 * 1000;
+
// Wall-clock ceiling for one pass. Per-provider spacing is compressed rather
// than allowed to push a pass past this, so a large fleet still finishes well
// inside the interval it is scheduled on and the dashboard never shows
@@ -381,6 +386,9 @@ export async function probeKeyValidity(keyId: number): Promise<KeyProbeOutcome>
// #1459: no probe for a provider that forbids them; the cooldown simply
// runs out, as it would after an inconclusive probe.
if (provider.supportsKeyValidation === false) return 'error';
+ // #1599: the probe would be the same empty search the health pass no
+ // longer sends on a schedule; let the cooldown run out instead.
+ if (provider.supportsKeyPolling === false) return 'error';
const apiKey = decrypt(row.encrypted_key, row.iv, row.auth_tag);
// Same reasoning as checkKeyHealth: probe through the key's own proxy (#590).
@@ -446,6 +454,10 @@ export interface HealthPassOptions {
* Used by the dashboard's "check all" button and the post-wake re-probe,
* where the point is an immediate, complete picture. */
force?: boolean;
+ /** Someone pressed "Check all": also validate keys on providers that must
+ * not be polled (#1599). The post-wake re-probe is forced but automatic, so
+ * it leaves them alone. */
+ manual?: boolean;
/** Test seams: injectable clock, sleep, probe and pool size, mirroring the
* cooldown-probe pass so a pacing test needs no real timers. */
now?: () => number;
@@ -526,6 +538,16 @@ async function runHealthPass(opts: HealthPassOptions): Promise<HealthPassResult>
const skippedKeyIds: number[] = [];
const skipMs = opts.force ? 0 : getValidationRateLimitSkipMs();
const due = rows.filter(row => {
+ // #1599: a provider whose key check is an empty search gets one check per
+ // new key, not one every pass. Applies to forced automatic passes too.
+ if (!opts.manual && resolveProvider(row.platform as Platform, row.base_url)?.supportsKeyPolling === false) {
+ const floorMs = row.status === 'error' ? NO_POLL_ERROR_REPROBE_MS : Infinity;
+ if (row.age_ms !== null && row.age_ms < floorMs) {
+ skippedKeyIds.push(row.id);
+ return false;
+ }
+ return true;
+ }
if (opts.force) return true;
// A key the provider just rate-limited stays out until the skip window
// passes — even one parked at 'error'. A 429 is fresher, more specific