Error Handling for AI Apps: The Fallback Chain

// Fallback chain implementation
async function generateWithFallback(
  prompt: string,
  context: RequestContext
): Promise<GenerationResult> {
  // Level 1: Primary model
  try {
    return await generateWithClaude(prompt, 'claude-sonnet-4-20250514', context);
  } catch (err) {
    logFailure('primary_model', err, context);
  }

  // Level 2: Faster model  
  try {
    return await generateWithClaude(prompt, 'claude-haiku-4-20250514', context);
  } catch (err) {
    logFailure('fallback_model', err, context);
  }

  // Level 3: Semantic cache
  const cached = await semanticCache.findSimilar(prompt, threshold: 0.92);
  if (cached) {
    return { content: cached.response, source: 'cache', quality: 'cached' };
  }

  // Level 4: Rule-based default
  const ruleBasedResponse = generateRuleBased(prompt, context.featureId);
  if (ruleBasedResponse) {
    return { content: ruleBasedResponse, source: 'rule-based', quality: 'template' };
  }

  // Level 5: Honest degradation
  return {
    content: null,
    source: 'unavailable',
    quality: 'none',
    message: 'AI features are temporarily unavailable. You can continue manually.',
  };
}

import { z } from 'zod';

// Strict input validation schema
const aiRequestSchema = z.object({
  // Length limits that account for your prompt overhead
  userContent: z.string()
    .min(1, 'Content cannot be empty')
    .max(8000, 'Content exceeds maximum length of 8,000 characters'),

  // Context data similarly bounded
  documentContext: z.string()
    .max(16000, 'Document context exceeds maximum length')
    .optional(),

  // Enum types prevent injection attempts
  tone: z.enum(['professional', 'casual', 'technical', 'friendly']),

  language: z.string()
    .regex(/^[a-z]{2}(-[A-Z]{2})?$/, 'Invalid language code')
    .default('en'),
});

type AIRequest = z.infer<typeof aiRequestSchema>;

async function handleAIRequest(rawInput: unknown): Promise<Response> {
  const parseResult = aiRequestSchema.safeParse(rawInput);

  if (!parseResult.success) {
    return Response.json({
      error: {
        code: 'VALIDATION_ERROR',
        message: 'Invalid request',
        details: parseResult.error.errors.map(e => ({
          field: e.path.join('.'),
          message: e.message,
        })),
      }
    }, { status: 400 });
  }

  // Input is now type-safe and validated
  return processValidatedRequest(parseResult.data);
}

import DOMPurify from 'isomorphic-dompurify';

interface SanitizedOutput {
  content: string;
  wasModified: boolean;
  violations: string[];
}

function sanitizeAIOutput(
  rawOutput: string,
  config: SanitizationConfig
): SanitizedOutput {
  const violations: string[] = [];
  let content = rawOutput;

  // Remove any HTML if plain text expected
  if (config.expectedFormat === 'plain-text') {
    const cleaned = DOMPurify.sanitize(rawOutput, { ALLOWED_TAGS: [] });
    if (cleaned !== rawOutput) {
      violations.push('HTML content detected and removed');
      content = cleaned;
    }
  }

  // If HTML is allowed, still sanitize
  if (config.expectedFormat === 'html') {
    content = DOMPurify.sanitize(rawOutput, {
      ALLOWED_TAGS: ['p', 'br', 'strong', 'em', 'ul', 'ol', 'li', 'code', 'pre'],
      ALLOWED_ATTR: [],
    });
  }

  // Check for system prompt leakage
  if (config.systemPromptKeywords) {
    for (const keyword of config.systemPromptKeywords) {
      if (content.toLowerCase().includes(keyword.toLowerCase())) {
        violations.push(`System prompt keyword detected: ${keyword}`);
        content = content.replace(new RegExp(keyword, 'gi'), '[redacted]');
      }
    }
  }

  // Enforce max output length
  if (config.maxLength && content.length > config.maxLength) {
    violations.push(`Output truncated from ${content.length} to ${config.maxLength} characters`);
    content = content.substring(0, config.maxLength);
  }

  return {
    content,
    wasModified: violations.length > 0,
    violations,
  };
}

class AICircuitBreaker {
  private failureCount = 0;
  private lastFailureTime = 0;
  private state: 'closed' | 'open' | 'half-open' = 'closed';

  private readonly FAILURE_THRESHOLD = 5;
  private readonly RECOVERY_TIMEOUT_MS = 30_000;
  private readonly SUCCESS_THRESHOLD = 2;
  private successCount = 0;

  async call<T>(fn: () => Promise<T>): Promise<T> {
    if (this.state === 'open') {
      const timeSinceLastFailure = Date.now() - this.lastFailureTime;
      if (timeSinceLastFailure < this.RECOVERY_TIMEOUT_MS) {
        throw new CircuitOpenError('AI service circuit breaker is open');
      }
      // Transition to half-open: allow one test request
      this.state = 'half-open';
    }

    try {
      const result = await fn();
      this.onSuccess();
      return result;
    } catch (err) {
      this.onFailure();
      throw err;
    }
  }

  private onSuccess() {
    this.failureCount = 0;
    if (this.state === 'half-open') {
      this.successCount++;
      if (this.successCount >= this.SUCCESS_THRESHOLD) {
        this.state = 'closed';
        this.successCount = 0;
      }
    }
  }

  private onFailure() {
    this.failureCount++;
    this.lastFailureTime = Date.now();
    if (this.failureCount >= this.FAILURE_THRESHOLD) {
      this.state = 'open';
    }
  }

  getState() { return this.state; }
}

async function withRetry<T>(
  fn: () => Promise<T>,
  options: RetryOptions = {}
): Promise<T> {
  const {
    maxAttempts = 3,
    baseDelayMs = 500,
    maxDelayMs = 10_000,
    retryableErrors = ['rate_limit', 'overloaded', 'timeout'],
  } = options;

  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      return await fn();
    } catch (err) {
      const isRetryable = retryableErrors.some(code =>
        err instanceof Error && err.message.includes(code)
      );

      if (!isRetryable || attempt === maxAttempts) throw err;

      // Exponential backoff with jitter
      const exponentialDelay = baseDelayMs * Math.pow(2, attempt - 1);
      const jitter = Math.random() * baseDelayMs;
      const delay = Math.min(exponentialDelay + jitter, maxDelayMs);

      await sleep(delay);
    }
  }

  throw new Error('Max retry attempts exceeded');
}

// Typed error messages by failure mode
const AI_ERROR_MESSAGES: Record<string, UserFacingError> = {
  service_unavailable: {
    title: 'AI features temporarily unavailable',
    description: 'Our AI service is experiencing issues. Your work has been saved.',
    action: 'You can continue editing manually, or try again in a few minutes.',
    canRetry: true,
  },
  rate_limit: {
    title: 'Too many requests',
    description: 'You have reached your hourly AI usage limit.',
    action: 'Your limit resets in {resetTime}. Upgrade your plan for higher limits.',
    canRetry: false,
  },
  content_too_long: {
    title: 'Content is too long',
    description: 'Your content exceeds the maximum length for this feature.',
    action: 'Shorten your content to under {maxLength} characters, or use the full document feature.',
    canRetry: false,
  },
  output_invalid: {
    title: 'AI response was invalid',
    description: 'The AI generated an unexpected response. This has been logged.',
    action: 'Please try again. If this keeps happening, contact support.',
    canRetry: true,
  },
};