Voice Agents That Fail Gracefully

{
  "error": "PAYMENT_PROCESSOR_TIMEOUT",
  "code": 5007,
  "details": "Gateway timeout after 30s"
}

import { RealtimeClient } from '@openai/realtime-api-beta';

const client = new RealtimeClient({
  apiKey: process.env.OPENAI_API_KEY,
  model: 'gpt-realtime',
});

// Error handler with context preservation
async function handleError(error, conversationContext) {
  const errorExplanation = translateError(error);
  const recovery = determineRecoveryAction(error);
  
  await client.sendText({
    text: errorExplanation.message,
    instructions: `
      Apologize sincerely but briefly.
      Explain what happened in plain language.
      Offer clear next steps.
      Don't make the user feel like it's their fault.
    `
  });
  
  // Log error with full context
  await logErrorWithContext({
    error: error,
    explanation: errorExplanation,
    conversation: conversationContext,
    timestamp: new Date().toISOString()
  });
  
  // Offer recovery options
  await offerRecovery(recovery);
}

function translateError(error) {
  const errorTranslations = {
    'PAYMENT_PROCESSOR_TIMEOUT': {
      message: "I'm sorry, the payment didn't go through. This usually happens when the card network is running slow. Your card wasn't charged.",
      category: 'payment',
      severity: 'recoverable'
    },
    'INVALID_INPUT_FORMAT': {
      message: "I didn't quite catch that correctly. Could you repeat it in a different way?",
      category: 'validation',
      severity: 'user_fixable'
    },
    'API_RATE_LIMIT_EXCEEDED': {
      message: "We're getting a lot of requests right now. Let me try again in just a moment.",
      category: 'system',
      severity: 'temporary'
    },
    'NETWORK_CONNECTION_LOST': {
      message: "I lost connection for a second. I'm back now. Where were we?",
      category: 'network',
      severity: 'recoverable'
    },
    'DATABASE_QUERY_TIMEOUT': {
      message: "This is taking longer than expected. Let me try a different approach.",
      category: 'system',
      severity: 'workaround_available'
    }
  };
  
  return errorTranslations[error.code] || {
    message: "Something unexpected happened. Let me see if I can help another way.",
    category: 'unknown',
    severity: 'unknown'
  };
}

function determineRecoveryAction(error) {
  const recoveryActions = {
    'PAYMENT_PROCESSOR_TIMEOUT': {
      actions: [
        'Retry payment',
        'Use different payment method',
        'Save order and try later'
      ],
      autoRetry: true,
      waitTime: 2000 // 2 seconds
    },
    'INVALID_INPUT_FORMAT': {
      actions: ['Ask user to rephrase', 'Provide example format'],
      autoRetry: false
    },
    'API_RATE_LIMIT_EXCEEDED': {
      actions: ['Wait and retry', 'Use cached data if available'],
      autoRetry: true,
      waitTime: 5000 // 5 seconds
    },
    'NETWORK_CONNECTION_LOST': {
      actions: ['Reconnect', 'Resume from last checkpoint'],
      autoRetry: true,
      waitTime: 1000 // 1 second
    }
  };
  
  return recoveryActions[error.code] || {
    actions: ['Ask user for preference', 'Offer human handoff'],
    autoRetry: false
  };
}

async function offerRecovery(recovery) {
  if (recovery.autoRetry && recovery.waitTime) {
    // Auto-retry with user notification
    await client.sendText({
      text: `Let me try that again for you.`,
      instructions: "Keep tone calm and confident."
    });
    
    await new Promise(resolve => setTimeout(resolve, recovery.waitTime));
    // Retry operation here
    
  } else {
    // Offer manual alternatives
    const optionsText = recovery.actions.join(' or ');
    await client.sendText({
      text: `Would you like me to ${optionsText}?`,
      instructions: "Present options clearly and wait for user choice."
    });
  }
}

class ConversationCheckpoint {
  constructor() {
    this.checkpoints = [];
  }
  
  saveCheckpoint(state) {
    this.checkpoints.push({
      timestamp: new Date(),
      state: JSON.parse(JSON.stringify(state)), // Deep copy
      step: state.currentStep
    });
  }
  
  async restoreFromError(errorType) {
    // Find last good state before error
    const lastCheckpoint = this.checkpoints[this.checkpoints.length - 1];
    
    if (lastCheckpoint) {
      await client.sendText({
        text: "I saved where we were. Let's pick up from there.",
        instructions: `Resume conversation from: ${lastCheckpoint.step}`
      });
      
      return lastCheckpoint.state;
    }
    
    return null;
  }
}

const checkpoint = new ConversationCheckpoint();

// Save checkpoints at key moments
client.on('conversation.item.completed', (event) => {
  if (event.item.type === 'user_input') {
    checkpoint.saveCheckpoint({
      currentStep: event.item.step,
      data: event.item.data,
      conversationHistory: event.conversation
    });
  }
});

function formulateApology(errorSeverity) {
  const apologies = {
    minor: "My mistake.",
    moderate: "I'm sorry about that.",
    major: "I'm really sorry—that shouldn't have happened."
  };
  
  return apologies[errorSeverity] || apologies.moderate;
}