diegosouzapw/OmniRoute · error

STRICT_ZERO_COST: usage refresh failed, treating as UNKNOWN

Error message

STRICT_ZERO_COST: usage refresh failed, treating as UNKNOWN

What it means

STRICT_ZERO_COST mode guard: a free-access usage refresh (fetching remaining allowance from the provider) threw, so the cache is written with status UNKNOWN instead of SAFE/EXHAUSTED. This is deliberate — an unknown state must not be treated as free quota in strict zero-cost mode — and the next refresh cycle will retry. Causes include network errors, provider endpoint changes, and auth failures on the usage endpoint.

Solutions

  1. Inspect the underlying error (network, auth, schema) from the usage-refresh fetch and fix the root cause.
  2. Verify the usage endpoint URL/auth for the free provider has not changed.
  3. Rely on the retry on the next cache-expiry cycle; consider alerting if UNKNOWN persists.
Defensive patterns

Strategy: try-catch

When it happens

Trigger: Thrown at open-sse/services/autoCombo/freeAccessQuota.ts:168 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of diegosouzapw/OmniRoute@a179ffed5b (2026-08-25). Data as JSON: /api/errors/2d0fdde3b40a8449. Report an issue: GitHub.

Appendix: source

Thrown at open-sse/services/autoCombo/freeAccessQuota.ts:168

    );
    const remaining = extractRemainingAllowance(usage);
    const state: FreeAccessState = {
      status: remaining === null ? "UNKNOWN" : remaining > 0 ? "SAFE" : "EXHAUSTED",
      remainingFreeAllowance: remaining,
      resetAt:
        usage &&
        typeof usage === "object" &&
        typeof (usage as Record<string, unknown>).resetAt === "string"
          ? ((usage as Record<string, unknown>).resetAt as string)
          : null,
      checkedAt: new Date().toISOString(),
    };
    cache.set(key, { state, fetchedAtMs: Date.now() });
  } catch (err) {
    // A failed lookup must never leave a stale SAFE entry behind — drop it so
    // the next read is a clean cache miss (UNKNOWN), not a lucky reuse.
    cache.delete(key);
    log.warn("AUTO", "STRICT_ZERO_COST: usage refresh failed, treating as UNKNOWN", {
      provider,
      err: err instanceof Error ? err.message : String(err),
    });
  } finally {
    inFlight.delete(key);
  }
}

/**
 * Synchronous read for `strictZeroCostFilter.ts`. Returns `undefined` when
 * there's no usage adapter for this provider at all (a permanent UNKNOWN, no
 * point ever refreshing), or on a cold/stale cache — in both cases a
 * background refresh is kicked off (fire-and-forget, subject to the
 * concurrency cap above) so a *later* read can benefit, but this call itself
 * never blocks or throws.
 */
export function resolveFreeAccessState(
  provider: string,

View on GitHub (pinned to a179ffed5b)