Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript
4.7 KB
Raw Blame
/**
 * Shared, duck-typed error classification helpers.
 *
 * These helpers work on any error whose shape matches HttpErrorLike — no
 * instanceof checks, so OpenAI/Anthropic/ZAI/Bailian/future providers all
 * share the same status-code branch.
 */
import { LlmErrorCode } from '../core/errors'
import type { ClassifiedError } from './index'

export interface HttpErrorLike {
  status?: number
  error?: { code?: string; type?: string; message?: string }
  message?: string
}

function isHttpErrorLike(err: unknown): err is HttpErrorLike {
  return typeof err === 'object' && err !== null && ('status' in err || 'error' in err)
}

export function classifyByHttpStatus(err: unknown): ClassifiedError | null {
  if (!isHttpErrorLike(err)) return null
  const e = err as HttpErrorLike
  const rawMsg = e.error?.message ?? e.message ?? 'Unknown LLM error'
  const bodyCode = e.error?.code
  const bodyType = e.error?.type
  // Additive diagnostics threaded onto every classification (spec 02, Pieza A).
  const diag: Pick<ClassifiedError, 'httpStatus' | 'providerCode'> = {
    httpStatus: typeof e.status === 'number' ? e.status : undefined,
    providerCode: bodyCode ?? bodyType,
  }

  // Body-level signals take precedence over raw HTTP status. To add new
  // body-code mappings (e.g., "rate_limit_exceeded", "context_length_exceeded"),
  // extend this if-block — do NOT add them to the switch below, which only
  // considers HTTP status.
  if (bodyCode === 'insufficient_quota' || bodyType === 'insufficient_quota') {
    return { code: LlmErrorCode.InsufficientQuota, retryable: false, message: rawMsg, ...diag }
  }
  // Model retired OR not accessible to this account — providers surface it as a
  // body code even on a non-404 status. Ambiguous by design (the runtime never
  // concludes the catalog is stale — see spec 02 §3.1); it only reports "not
  // available". Non-retryable and NOT a failover trigger.
  if (bodyCode === 'model_not_found' || bodyType === 'model_not_found') {
    return { code: LlmErrorCode.ModelNotAvailable, retryable: false, message: rawMsg, ...diag }
  }
  // A genuinely invalid credential (distinct from a 403 access/billing denial).
  if (bodyCode === 'invalid_api_key' || bodyType === 'invalid_api_key') {
    return { code: LlmErrorCode.AuthenticationFailed, retryable: false, message: rawMsg, ...diag }
  }

  switch (e.status) {
    case 401:
    case 403:
      // 401 (bad key) and 403 (forbidden: account access / IAM permission) are
      // both identity/authorization failures — the caller must fix credentials
      // or grants before this provider serves. Genuine quota has its own channel
      // (body `insufficient_quota`, Vertex RESOURCE_EXHAUSTED, Bedrock
      // ServiceQuotaExceededException), so 403 stays on the `auth` failover class
      // uniformly across all four provider arms (R1-M1). The 401-vs-403 detail
      // survives in `httpStatus`/`providerCode` (diag), not in the class.
      return { code: LlmErrorCode.AuthenticationFailed, retryable: false, message: rawMsg, ...diag }
    case 402:
      return { code: LlmErrorCode.InsufficientQuota, retryable: false, message: rawMsg, ...diag }
    case 404:
      // Retired or inaccessible model — indistinguishable by API (spec 02 §3.1).
      // Non-retryable so the loop does not retry, and mapped to `null` failover
      // class so it does not silently divert cross-provider.
      return { code: LlmErrorCode.ModelNotAvailable, retryable: false, message: rawMsg, ...diag }
    case 429:
      return { code: LlmErrorCode.RateLimited, retryable: true, message: rawMsg, ...diag }
    case 503:
    case 529:
      return { code: LlmErrorCode.ModelOverloaded, retryable: true, message: rawMsg, ...diag }
  }

  if (typeof e.status === 'number' && e.status >= 500 && e.status < 600) {
    return { code: LlmErrorCode.ModelOverloaded, retryable: true, message: rawMsg, ...diag }
  }
  if (e.status === 400) {
    return { code: LlmErrorCode.ApiCallFailed, retryable: false, message: rawMsg, ...diag }
  }
  return null
}

/**
 * Fallback classifier for errors whose shape does not match HttpErrorLike.
 *
 * Defaults to `retryable: true` because the common cause is a transport
 * failure (network down, DNS failure, socket closed, timeout) which may
 * succeed on retry. Providers with a non-HTTP SDK error shape MUST
 * intercept those shapes in their own `classifyError` before falling
 * through to this helper — otherwise permanent errors would be
 * misclassified as transient. See ClaudeProvider.classifyError for the
 * Anthropic credit-balance quirk that demonstrates this pattern.
 */
export function classifyUnknown(err: unknown): ClassifiedError {
  const msg = err instanceof Error ? err.message : String(err)
  return { code: LlmErrorCode.ApiCallFailed, retryable: true, message: msg }
}