{
  "error": {
    "type": "card_error",
    "code": "card_declined",
    "message": "Your card was declined",
    "param": "payment_method",
    "request_id": "req_abc123"
  }
}

class PaymentErrorHandler {
  constructor() {
    this.maxRetries = 3;
    this.retryableErrors = ['api_error', 'rate_limit_error'];
    this.nonRetryableErrors = ['authentication_error', 'invalid_request_error'];
  }
  
  async handlePaymentRequest(paymentData) {
    let attempt = 0;
    
    while (attempt < this.maxRetries) {
      try {
        const response = await this.makePaymentRequest(paymentData);
        return response;
        
      } catch (error) {
        attempt++;
        
        // Don't retry on client errors
        if (this.isClientError(error)) {
          throw this.formatUserError(error);
        }
        
        // Don't retry on final attempt
        if (attempt >= this.maxRetries) {
          throw error;
        }
        
        // Calculate delay with exponential backoff
        const delay = this.calculateRetryDelay(attempt, error);
        await this.sleep(delay);
      }
    }
  }
  
  isClientError(error) {
    return error.status >= 400 && error.status < 500;
  }
  
  calculateRetryDelay(attempt, error) {
    // Use retry_after header if available (rate limiting)
    if (error.retry_after) {
      return error.retry_after * 1000;
    }
    
    // Exponential backoff with jitter
    const baseDelay = 1000; // 1 second
    const maxDelay = 30000;  // 30 seconds
    const exponentialDelay = baseDelay * Math.pow(2, attempt - 1);
    const jitter = Math.random() * 1000;
    
    return Math.min(maxDelay, exponentialDelay + jitter);
  }
  
  formatUserError(error) {
    const userMessages = {
      'card_declined': 'Your card was declined. Please try a different payment method.',
      'insufficient_funds': 'Your card has insufficient funds. Please use a different card.',
      'expired_card': 'Your card has expired. Please update your payment information.',
      'incorrect_cvc': 'The security code is incorrect. Please check and try again.',
      'invalid_api_key': 'Authentication failed. Please contact support.'
    };
    
    return {
      userMessage: userMessages[error.code] || 'An error occurred processing your payment.',
      errorCode: error.code,
      canRetry: this.retryableErrors.includes(error.type)
    };
  }
}

// Error message mapping
const getUserErrorMessage = (error) => {
  const messages = {
    // Card errors
    'card_declined': 'Your card was declined. Please try a different payment method or contact your bank.',
    'insufficient_funds': 'Your account has insufficient funds. Please use a different card or add funds to your account.',
    'expired_card': 'Your card has expired. Please update your payment information with a valid card.',
    'incorrect_cvc': 'The security code is incorrect. Please check the 3-4 digit code on your card and try again.',
    'lost_card': 'Your card has been reported lost. Please use a different payment method.',
    'stolen_card': 'Your card has been reported stolen. Please use a different payment method.',
    
    // Processing errors
    'processing_error': 'We encountered an error processing your payment. Please try again.',
    'issuer_not_available': 'Your card issuer is temporarily unavailable. Please try again later.',
    'try_again_later': 'Please try again in a few minutes.',
    
    // Request errors
    'invalid_amount': 'The payment amount is invalid. Please check and try again.',
    'currency_not_supported': 'This currency is not supported. Please select a different currency.',
    
    // General fallback
    'default': 'An unexpected error occurred. Please try again or contact support if the problem persists.'
  };
  
  return messages[error.code] || messages.default;
};

// Usage in UI
const handlePaymentError = (error) => {
  const userMessage = getUserErrorMessage(error);
  
  // Display to user
  showErrorMessage(userMessage);
  
  // Log technical details for debugging
  console.error('Payment error:', {
    code: error.code,
    type: error.type,
    requestId: error.request_id,
    timestamp: new Date().toISOString()
  });
};

// Include request ID in error logging
const logPaymentError = (error, context) => {
  const logEntry = {
    timestamp: new Date().toISOString(),
    level: 'error',
    message: 'Payment processing failed',
    error: {
      type: error.type,
      code: error.code,
      message: error.message,
      request_id: error.request_id
    },
    context: {
      user_id: context.userId,
      payment_amount: context.amount,
      payment_method: context.paymentMethod,
      session_id: context.sessionId
    }
  };
  
  console.error(JSON.stringify(logEntry));
  
  // Send to monitoring service
  errorMonitoring.captureError(logEntry);
};

class ErrorMonitoring {
  constructor() {
    this.errorCounts = new Map();
    this.alertThresholds = {
      'card_declined': 0.15, // Alert if > 15% decline rate
      'api_error': 0.01,     // Alert if > 1% API errors
      'timeout': 0.05        // Alert if > 5% timeouts
    };
  }
  
  recordError(errorType, errorCode) {
    const key = `${errorType}:${errorCode}`;
    const current = this.errorCounts.get(key) || 0;
    this.errorCounts.set(key, current + 1);
    
    this.checkAlertThresholds(errorType, errorCode);
  }
  
  checkAlertThresholds(errorType, errorCode) {
    const threshold = this.alertThresholds[errorCode];
    if (!threshold) return;
    
    const errorRate = this.calculateErrorRate(errorType, errorCode);
    if (errorRate > threshold) {
      this.sendAlert({
        type: 'high_error_rate',
        errorCode: errorCode,
        currentRate: errorRate,
        threshold: threshold
      });
    }
  }
  
  sendAlert(alertData) {
    // Send to monitoring service
    console.warn('Error rate alert:', alertData);
  }
}

// Test different error scenarios
describe('Payment Error Handling', () => {
  const testCards = {
    declined: '4000000000000002',
    insufficientFunds: '4000000000009995',
    expired: '4000000000000069',
    incorrectCvc: '4000000000000127'
  };
  
  test('handles declined card gracefully', async () => {
    const payment = await createPayment({
      card: testCards.declined,
      amount: 1000
    });
    
    expect(payment.error.code).toBe('card_declined');
    expect(payment.error.type).toBe('card_error');
  });
  
  test('handles rate limiting', async () => {
    // Simulate rate limit by making many requests
    const promises = Array(100).fill().map(() => 
      createPayment({ card: '4111111111111111', amount: 100 })
    );
    
    const results = await Promise.allSettled(promises);
    const rateLimited = results.some(r => 
      r.status === 'rejected' && 
      r.reason.error.code === 'rate_limit_exceeded'
    );
    
    expect(rateLimited).toBe(true);
  });
});