Skip to content

Never stop coding. Free MIT AI gateway: one endpoint, 375 providers (150+ free), 1,400+ models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline & Copilot. Quota-aware auto-fallback, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 900+ contributors

9.7 KB
Raw Blame
export type ErrorInfo = {
  type: string;
  code: string;
};

export type ConfiguredErrorReason =
  | "auth_error"
  | "quota_exhausted"
  | "rate_limit_exceeded"
  | "model_capacity"
  | "server_error"
  | "unknown";

export type ErrorRule = {
  id: string;
  text?: string;
  status?: number;
  reason?: ConfiguredErrorReason;
  cooldownMs?: number;
  backoff?: boolean;
};

// OpenAI-compatible error types mapping (client-facing)
export const ERROR_TYPES: Record<number, ErrorInfo> = {
  400: { type: "invalid_request_error", code: "bad_request" },
  401: { type: "authentication_error", code: "invalid_api_key" },
  402: { type: "billing_error", code: "payment_required" },
  403: { type: "permission_error", code: "permission_denied" },
  404: { type: "invalid_request_error", code: "model_not_found" },
  406: { type: "invalid_request_error", code: "model_not_supported" },
  410: { type: "invalid_request_error", code: "model_shutdown" },
  429: { type: "rate_limit_error", code: "rate_limit_exceeded" },
  499: { type: "client_disconnected", code: "client_disconnected" },
  500: { type: "server_error", code: "internal_server_error" },
  502: { type: "server_error", code: "bad_gateway" },
  503: { type: "server_error", code: "service_unavailable" },
  504: { type: "server_error", code: "gateway_timeout" },
};

// Default error messages per status code (client-facing)
export const DEFAULT_ERROR_MESSAGES: Record<number, string> = {
  400: "Bad request",
  401: "Invalid API key provided",
  402: "Payment required",
  403: "Permission denied",
  404: "Model not found",
  406: "Model not supported",
  410: "Model has been shut down",
  429: "Rate limit exceeded",
  499: "Client disconnected",
  500: "Internal server error",
  502: "Bad gateway - upstream provider error",
  503: "Service temporarily unavailable",
  504: "Gateway timeout",
};

// Exponential backoff config for rate limits.
// Preserve OmniRoute's existing 2-minute cap to avoid changing runtime behavior.
export const BACKOFF_CONFIG = {
  base: 1000,
  max: 2 * 60 * 1000,
  maxLevel: 15,
};

export const TRANSIENT_COOLDOWN_MS = 5 * 1000;

// Cooldown durations (ms)
export const COOLDOWN_MS = {
  unauthorized: 2 * 60 * 1000,
  paymentRequired: 2 * 60 * 1000,
  notFound: 2 * 60 * 1000,
  notFoundLocal: 5 * 1000,
  transientInitial: TRANSIENT_COOLDOWN_MS,
  transientMax: 60 * 1000,
  transient: TRANSIENT_COOLDOWN_MS,
  requestNotAllowed: 5 * 1000,
  // Anthropic OAuth 403 "Request not allowed" (#12859): a per-request refusal
  // on a healthy token. chatCore excludes the connection for requestRejected
  // after the first refusal, requestRejectedRepeat after the second, and bans
  // it on the third consecutive one (services/requestRejectedStreak.ts).
  requestRejected: 5 * 60 * 1000,
  requestRejectedRepeat: 15 * 60 * 1000,
  rateLimit: 2 * 60 * 1000,
  serviceUnavailable: 2 * 1000,
  authExpired: 2 * 60 * 1000,
  // Google regional-availability refusal: nothing changes region-wise on the
  // account, so re-probe only after a long window (or when the operator routes
  // egress through a supported-region proxy).
  geoBlocked: 24 * 60 * 60 * 1000,
  // Antigravity BYOP (GCP_PROJECT_REQUIRED): nothing changes on the account
  // until the operator enters a Project ID, so keep the connection excluded
  // from selection for a long window (mirrors the geo-blocked treatment).
  gcpProjectRequired: 24 * 60 * 60 * 1000,
};

/**
 * Shared rules for account fallback classification.
 * Checked top-to-bottom: text rules first, then status rules.
 */
export const ERROR_RULES: ErrorRule[] = [
  {
    id: "no_credentials",
    text: "no credentials",
    cooldownMs: COOLDOWN_MS.notFound,
    reason: "auth_error",
  },
  {
    // For provider `claude` this text is classified REQUEST_REJECTED and the
    // connection-level cooldown is written by chatCore before the fallback
    // layer runs (#12859); markAccountUnavailable then keeps the longer
    // cooldown. This 5 s rule still serves every other provider.
    id: "request_not_allowed",
    text: "request not allowed",
    cooldownMs: COOLDOWN_MS.requestNotAllowed,
    reason: "rate_limit_exceeded",
  },
  {
    id: "improperly_formed_request",
    text: "improperly formed request",
    cooldownMs: 0,
    reason: "model_capacity",
  },
  { id: "rate_limit", text: "rate limit", backoff: true, reason: "rate_limit_exceeded" },
  {
    id: "too_many_requests",
    text: "too many requests",
    backoff: true,
    reason: "rate_limit_exceeded",
  },
  {
    id: "hour_quota_exceeded",
    text: "hour quota",
    backoff: true,
    reason: "quota_exhausted",
  },
  {
    id: "quota_has_been_exceeded",
    text: "quota has been exceeded",
    backoff: true,
    reason: "quota_exhausted",
  },
  {
    id: "quota_exceeded",
    text: "quota exceeded",
    backoff: true,
    reason: "quota_exhausted",
  },
  {
    id: "quota_will_reset",
    text: "quota will reset",
    backoff: true,
    reason: "quota_exhausted",
  },
  {
    id: "capacity_exhausted",
    text: "exhausted your capacity",
    backoff: true,
    reason: "quota_exhausted",
  },
  {
    id: "quota_exhausted",
    text: "quota exhausted",
    backoff: true,
    reason: "quota_exhausted",
  },
  {
    id: "free_tier_exhausted",
    text: "free tier of the model has been exhausted",
    backoff: true,
    reason: "quota_exhausted",
  },
  {
    id: "out_of_extra_usage",
    text: "out of extra usage",
    backoff: true,
    reason: "quota_exhausted",
  },
  {
    id: "extra_usage_required",
    text: "extra usage required",
    backoff: true,
    reason: "quota_exhausted",
  },
  { id: "capacity", text: "capacity", backoff: true, reason: "model_capacity" },
  { id: "overloaded", text: "overloaded", backoff: true, reason: "model_capacity" },
  { id: "high_demand", text: "high demand", backoff: true, reason: "model_capacity" },
  { id: "status_401", status: 401, cooldownMs: 0, reason: "auth_error" },
  { id: "status_402", status: 402, cooldownMs: 0, reason: "quota_exhausted" },
  { id: "status_403", status: 403, cooldownMs: 0, reason: "unknown" },
  { id: "status_404", status: 404, cooldownMs: COOLDOWN_MS.notFound, reason: "unknown" },
  { id: "status_406", status: 406, backoff: true, reason: "server_error" },
  { id: "status_408", status: 408, backoff: true, reason: "server_error" },
  { id: "status_429", status: 429, backoff: true, reason: "rate_limit_exceeded" },
  { id: "status_500", status: 500, backoff: true, reason: "server_error" },
  { id: "status_502", status: 502, backoff: true, reason: "server_error" },
  { id: "status_503", status: 503, backoff: true, reason: "server_error" },
  { id: "status_504", status: 504, backoff: true, reason: "server_error" },
];

function normalizeErrorMessage(message: unknown): string {
  return String(message || "").toLowerCase();
}

export function getErrorInfo(statusCode: number): ErrorInfo {
  return (
    ERROR_TYPES[statusCode] ||
    (statusCode >= 500
      ? { type: "server_error", code: "internal_server_error" }
      : { type: "invalid_request_error", code: "" })
  );
}

export function getDefaultErrorMessage(statusCode: number): string {
  return DEFAULT_ERROR_MESSAGES[statusCode] || "An error occurred";
}

export function calculateBackoffCooldown(level = 0): number {
  const safeLevel = Math.max(0, Math.floor(level));
  const cooldown = BACKOFF_CONFIG.base * Math.pow(2, safeLevel);
  return Math.min(cooldown, BACKOFF_CONFIG.max);
}

export function matchErrorRuleByText(message: unknown): ErrorRule | null {
  const lower = normalizeErrorMessage(message);
  if (!lower) return null;
  return ERROR_RULES.find((rule) => rule.text && lower.includes(rule.text)) || null;
}

export function matchErrorRuleByStatus(statusCode: number): ErrorRule | null {
  return ERROR_RULES.find((rule) => rule.status === statusCode) || null;
}

export function findMatchingErrorRule(statusCode: number, message: unknown): ErrorRule | null {
  return matchErrorRuleByText(message) || matchErrorRuleByStatus(statusCode);
}

// #8248: NVIDIA NIM function-state DEGRADED — some NIM deployments signal a non-standard
// HTTP 400 whose body reports the backing "function" is DEGRADED (e.g. `Function id "<uuid>"
// submitted for inference is DEGRADED`) instead of a clean model-not-found/5xx. Bounded
// lookahead ({0,80}) — ReDoS-safe, no nested quantifiers.
const NIM_FUNCTION_DEGRADED_PATTERNS = [
  /\bfunction\b[\s\S]{0,80}?\bDEGRADED\b/i,
  /\bDEGRADED\b[\s\S]{0,80}?\bfunction\b/i,
];

export function isNimFunctionDegraded(errorText: string): boolean {
  return NIM_FUNCTION_DEGRADED_PATTERNS.some((p) => p.test(errorText));
}

export interface ServiceSupervisorCooldown {
  shouldFallback: true;
  cooldownMs: number;
  baseCooldownMs: number;
  newBackoffLevel: 0;
  reason: string;
  skipProviderBreaker: true;
}

/**
 * G-02: detect embedded service supervisor failures (X-Omni-Fallback-Hint: connection_cooldown).
 * These are NOT upstream AI provider failures — they are local supervisor state changes. Returns
 * a short 5s connection-cooldown decision (no provider circuit-breaker trip), or null when the
 * status/header don't match.
 */
export function serviceSupervisorCooldown(
  status: number,
  headers: Headers | Record<string, string> | null
): ServiceSupervisorCooldown | null {
  if (status !== 503 || !headers) return null;
  const hintValue =
    typeof (headers as Headers).get === "function"
      ? (headers as Headers).get("x-omni-fallback-hint")
      : (headers as Record<string, string>)["x-omni-fallback-hint"] ||
        (headers as Record<string, string>)["X-Omni-Fallback-Hint"];
  if (typeof hintValue !== "string" || hintValue.toLowerCase() !== "connection_cooldown") {
    return null;
  }
  return {
    shouldFallback: true,
    cooldownMs: 5_000,
    baseCooldownMs: 5_000,
    newBackoffLevel: 0,
    reason: "service_not_running",
    skipProviderBreaker: true,
  };
}