Error Recovery Patterns

function classifyError(status, error, attemptCount) {
  if (status >= 200 && status < 300) return 'success';

  if (status === 401) return 'persistent_recoverable';   // credential issue
  if (status === 403) return 'permanent';                // permission issue
  if (status === 404) {
    return attemptCount < 3 ? 'transient' : 'permanent';  // indexing delay vs. real miss
  }
  if (status === 409) {
    return error?.code === 'concurrent_modification' ? 'transient' : 'permanent';
  }

  if (status >= 400 && status < 500) return 'permanent'; // 4xx default
  if (status === 429) return 'transient';                 // rate limit
  if (status >= 500) return 'transient';                  // 5xx default

  // Network errors
  if (error?.code === 'ECONNREFUSED' || error?.code === 'ETIMEDOUT') return 'transient';

  return 'transient';                                     // default to retry
}

async function retryWithBackoff(fn, options = {}) {
  const {
    maxAttempts = 5,
    baseDelayMs = 1000,
    maxDelayMs = 60000,
    jitterFactor = 0.5,
  } = options;

  let lastError;
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      return await fn();
    } catch (err) {
      lastError = err;
      const category = classifyError(err.status, err.body, attempt);

      if (category === 'permanent') throw err;             // Don't retry
      if (category === 'persistent_recoverable') throw err; // Escalate, don't retry
      if (attempt === maxAttempts) throw err;

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

      console.warn(`Attempt ${attempt} failed, retrying in ${Math.round(delay)}ms`, { error: err.message });
      await sleep(delay);
    }
  }
  throw lastError;
}

async function makeRequest(url, options) {
  const response = await fetch(url, options);
  if (response.status === 429) {
    const retryAfterSeconds = parseInt(response.headers.get('Retry-After') || '60', 10);
    const err = new Error('Rate limited');
    err.status = 429;
    err.retryAfterMs = retryAfterSeconds * 1000;
    throw err;
  }
  return response;
}

async function retryHonoringRetryAfter(fn) {
  while (true) {
    try {
      return await fn();
    } catch (err) {
      if (err.status === 429 && err.retryAfterMs) {
        await sleep(err.retryAfterMs);
        continue;
      }
      throw err;
    }
  }
}

async function createContactDirectWithRecovery(donor) {
  try {
    const response = await fetch('https://api.virtuoussoftware.com/api/Contact', {
      method: 'POST',
      headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
      body: JSON.stringify(donor),
    });
    return await response.json();
  } catch (err) {
    if (err.code === 'ETIMEDOUT' || err.code === 'ECONNRESET') {
      // The request may have completed server-side even though we didn't get a response.
      // Check before retrying.
      const existing = await findContactByReference(donor.referenceSource, donor.referenceId);
      if (existing) return existing;
    }
    throw err;
  }
}

async function processWithDeadLetter(record, processFn) {
  try {
    await retryWithBackoff(() => processFn(record));
  } catch (err) {
    const category = classifyError(err.status, err.body);
    if (category === 'permanent' || category === 'persistent_recoverable') {
      await db.virtuous_dead_letter_queue.insert({
        customer_id: record.customer_id,
        original_record_id: record.id,
        operation_type: record.operation_type,
        original_payload: record.payload,
        status_code: err.status,
        error_message: err.message,
        attempt_count: err.attemptCount,
      });
    }
    throw err;
  }
}

class CircuitBreaker {
  constructor({ failureThreshold = 5, openDurationMs = 60000 }) {
    this.failureThreshold = failureThreshold;
    this.openDurationMs = openDurationMs;
    this.state = 'closed';
    this.failureCount = 0;
    this.openedAt = null;
  }

  async execute(fn) {
    if (this.state === 'open') {
      if (Date.now() - this.openedAt > this.openDurationMs) {
        this.state = 'half_open';
      } else {
        throw new Error('Circuit breaker open');
      }
    }

    try {
      const result = await fn();
      if (this.state === 'half_open') {
        this.state = 'closed';
        this.failureCount = 0;
      }
      return result;
    } catch (err) {
      if (this.state === 'half_open') {
        this.state = 'open';
        this.openedAt = Date.now();
        throw err;
      }
      this.failureCount++;
      if (this.failureCount >= this.failureThreshold) {
        this.state = 'open';
        this.openedAt = Date.now();
      }
      throw err;
    }
  }
}

console.error('Gift submission failed', {
  customer_id: customer.id,
  transaction_id: gift.transactionId,
  status_code: err.status,
  error_message: err.message,
  attempt: attemptCount,
  request_id: response.headers.get('X-Request-Id'),
});