UNPKG

@bitkyc08/opencodex

Version:

Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code

160 lines (140 loc) • 9.07 kB
/** * Presentation-only classification of an upstream failure into a small closed set of conditions. * * The output is what request logs and client-facing error text may name. It never carries input * bytes: callers pass bounded structured tokens (status, type, code, reason) and optionally the * upstream message, which is read here only through fixed lowercase keyword sets and never stored * or returned. Routing, retry and recovery keep using their own classifiers (src/lib/errors.ts); * this module must not feed them. */ import { isDefiniteContextOverflow } from "./context-overflow-verdict"; export const UPSTREAM_CONDITIONS = [ "auth_failed", "access_denied", "context_overflow", "location_unsupported", "account_verification_required", "billing_exhausted", "model_unavailable", "rate_limited", "upstream_unavailable", "upstream_failed", "request_rejected", ] as const; export type UpstreamCondition = typeof UPSTREAM_CONDITIONS[number]; const CONDITION_SET: ReadonlySet<string> = new Set(UPSTREAM_CONDITIONS); export function isUpstreamCondition(value: unknown): value is UpstreamCondition { return typeof value === "string" && CONDITION_SET.has(value); } export interface UpstreamConditionEvidence { status: number; type?: string; code?: string; reason?: string; message?: string; } // Structured tokens are compared after lowercasing; anything longer than this is not a token. const MAX_TOKEN_LENGTH = 128; // Keyword matching reads at most this much of the message. const MAX_MESSAGE_SCAN = 4096; const TRANSPORT_FAILURE_CODES: ReadonlySet<string> = new Set([ "upstream_reset_replay_refused", "upstream_closed_before_response", "upstream_no_response", ]); const STRUCTURED: ReadonlyArray<readonly [UpstreamCondition, ReadonlySet<string>]> = [ ["context_overflow", new Set(["context_length_exceeded", "string_above_max_length", "context_window_exceeded", "prompt_too_long"])], ["location_unsupported", new Set(["location_not_supported", "unsupported_country_region_territory", "unsupported_country", "user_location_is_not_supported"])], ["account_verification_required", new Set(["validation_required", "verification_required", "organization_verification_required"])], ["billing_exhausted", new Set(["insufficient_quota", "billing_hard_limit_reached", "usage_limit_reached", "usage_limit_exceeded", "1308", "monthly_request_count", "overage_request_limit_exceeded", "payment_required", "insufficient_balance", "credit_balance_too_low"])], ["model_unavailable", new Set(["model_not_found", "unsupported_model", "model_not_available", "model_not_supported", "deployment_not_found"])], ["rate_limited", new Set(["rate_limit_exceeded", "rate_limit_error", "too_many_requests", "throttling", "throttled", "rate_limited"])], ["upstream_unavailable", new Set(["server_is_overloaded", "overloaded_error", "service_unavailable", "unavailable"])], ["upstream_failed", TRANSPORT_FAILURE_CODES], ]; // Context overflow from message text uses the same verdict the combo router trusts, so a validation // error that merely quotes "prompt is too long" (an invalid tool name, for example) is not an overflow. const KEYWORDS: Readonly<Record<"location_unsupported" | "account_verification_required" | "billing_exhausted" | "model_unavailable" | "rate_limited", readonly string[]>> = { location_unsupported: ["location is not supported", "unsupported location", "not supported in your region", "region is not supported", "country, region, or territory", "not available in your country", "not available in your region"], account_verification_required: ["verify your organization", "organization must be verified", "verification required", "verify your account", "account verification"], billing_exhausted: ["insufficient quota", "quota exceeded", "quota exhausted", "exceeded your current quota", "run out of credits", "out of credits", "insufficient credits", "credit balance", "insufficient balance", "billing", "payment required"], model_unavailable: ["model not found", "model does not exist", "unsupported model", "not allowed to use this model", "does not have access to model", "model is not available", "no such model"], rate_limited: ["rate limit", "too many requests", "throttl"], }; function token(value: string | undefined): string | undefined { if (typeof value !== "string") return undefined; const trimmed = value.trim(); return trimmed && trimmed.length <= MAX_TOKEN_LENGTH ? trimmed.toLowerCase() : undefined; } function structuredCondition(tokens: readonly string[]): UpstreamCondition | undefined { for (const [condition, set] of STRUCTURED) { if (tokens.some(value => set.has(value))) return condition; } return undefined; } function mentions(message: string, condition: keyof typeof KEYWORDS): boolean { return KEYWORDS[condition].some(keyword => message.includes(keyword)); } /** * Match the fixed Claude refusal, not arbitrary links or quoted validation values. Only the portal * link may follow the sentence, so a different diagnostic appended after it (an invalid key, for * example) keeps its own classification instead of the verification guidance. */ export function isClaudeVerificationNotice(evidence: UpstreamConditionEvidence): boolean { return evidence.status === 403 && typeof evidence.message === "string" && /^your account can['’]t receive replies from claude right now\. you can find the next step in the anthropic verification portal:(?:\s*https:\/\/portal\.anthropic\.com\/verify\S*)?\s*$/i.test(evidence.message.trim()); } function statusFallback(status: number): UpstreamCondition | undefined { if (status === 401) return "auth_failed"; if (status === 403) return "access_denied"; if (status === 402) return "billing_exhausted"; if (status === 404) return "model_unavailable"; if (status === 429) return "rate_limited"; if (status === 503 || status === 529) return "upstream_unavailable"; if (status >= 500) return "upstream_failed"; if (status >= 400) return "request_rejected"; return undefined; } /** * Precedence starts with 401, then exact transport codes, then other structured evidence. * Keywords apply only to 4xx statuses. The bare status is the final fallback. */ export function classifyUpstreamCondition(evidence: UpstreamConditionEvidence): UpstreamCondition | undefined { const { status } = evidence; if (!Number.isInteger(status)) return undefined; if (status === 401) return "auth_failed"; const code = token(evidence.code); if (code !== undefined && TRANSPORT_FAILURE_CODES.has(code)) return "upstream_failed"; const tokens = [code, token(evidence.type), token(evidence.reason)].filter((value): value is string => value !== undefined); const structured = structuredCondition(tokens); if (structured) return structured; const message = typeof evidence.message === "string" ? evidence.message.slice(0, MAX_MESSAGE_SCAN).toLowerCase() : ""; if (message && status >= 400 && status < 500) { if (isDefiniteContextOverflow(status, evidence.message!.slice(0, MAX_MESSAGE_SCAN))) return "context_overflow"; if (mentions(message, "location_unsupported")) return "location_unsupported"; if (isClaudeVerificationNotice(evidence) || mentions(message, "account_verification_required")) return "account_verification_required"; // A 429 that names a rate limit is a rate limit even when it also mentions quota. if (status === 429 && mentions(message, "rate_limited")) return "rate_limited"; if (mentions(message, "billing_exhausted")) return "billing_exhausted"; if (mentions(message, "model_unavailable")) return "model_unavailable"; if (mentions(message, "rate_limited")) return "rate_limited"; } return statusFallback(status); } const MESSAGES: Readonly<Record<UpstreamCondition, string>> = { auth_failed: "The provider rejected the configured credentials.", access_denied: "The provider denied access to this request.", context_overflow: "The request exceeds the model's context window.", location_unsupported: "The provider does not serve this request from the current location.", account_verification_required: "The provider requires account verification before serving this model.", billing_exhausted: "The provider account has no remaining quota or credits.", model_unavailable: "The requested model is not available from the provider.", rate_limited: "The provider rate limit was reached; retry later.", upstream_unavailable: "The provider is temporarily unavailable; retry later.", upstream_failed: "The provider failed to complete the request.", request_rejected: "The provider rejected the request.", }; const PROVIDER_ID = /^[A-Za-z0-9._-]{1,64}$/; /** Proxy-written text for a condition; the provider id comes from configuration, never from an error. */ export function upstreamConditionMessage(condition: UpstreamCondition, providerId?: string): string { const base = MESSAGES[condition]; return providerId !== undefined && PROVIDER_ID.test(providerId) ? `${base} (provider: ${providerId})` : base; }