Manejo de Errores

{
  "statusCode": 400,
  "timestamp": "2025-04-23T12:34:56.000Z",
  "path": "/api/v1/organizations/org_.../merchants/mer_.../orders",
  "errorCode": "BAA00008",
  "message": "The destination account currency does not match the order destination currency."
}

async function retryWithBackoff(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      const status = error.response?.status;
      const isRetryable =
        status === 408 ||
        status === 429 ||
        (status >= 500 && status < 600) ||
        error.code === 'ECONNABORTED';
 
      const isLastAttempt = i === maxRetries - 1;
      if (!isRetryable || isLastAttempt) throw error;
 
      // Backoff exponencial con jitter: ~1s, 2s, 4s
      const delay = Math.pow(2, i) * 1000 + Math.random() * 500;
      await new Promise(r => setTimeout(r, delay));
    }
  }
}

async function createOrderAndWait(token, orgId, merchantId, payload) {
  const order = await createPayinOrder(token, orgId, merchantId, payload);
 
  if (order.status !== 'ON_HOLD') return order;
 
  // Haz polling hasta que la aprobación se resuelva — `flow order --wait` del
  // CLI hace esto por ti. Las integraciones de producción deberían escuchar
  // webhooks en vez de hacer polling (ver "Webhooks en Profundidad").
  for (let i = 0; i < 60; i++) {
    await new Promise(r => setTimeout(r, 5000));
    const refreshed = await getOrder(token, orgId, merchantId, order.id);
    if (refreshed.status !== 'ON_HOLD') return refreshed;
  }
 
  throw new Error(`Orden ${order.id} sigue en ON_HOLD tras 5 minutos`);
}

async function createPayinWithFallback(orderBase) {
  const attempts = [
    { method: 'PSE', extra: { bankAccount: { name: 'BANCOLOMBIA' } } },
    { method: 'NEQUI' },
  ];
 
  for (const pm of attempts) {
    try {
      return await createPayinOrder(token, orgId, merchantId, {
        ...orderBase,
        paymentMethods: [pm],
      });
    } catch (error) {
      const code = error.response?.data?.errorCode;
      const retryable = ['PMP00012', 'PMP00017', 'PMP00003', 'PMP00008'];
      if (!retryable.includes(code)) throw error;
    }
  }
 
  throw new Error('No hay método de pago disponible para este país/moneda');
}

function translateErrorToUser(error) {
  const code = error.response?.data?.errorCode;
  const userMessages = {
    BAA00014: 'No tenemos saldo suficiente para completar este pago ahora mismo.',
    DC00010: 'Por favor revisa el número de documento.',
    QE00003: 'Esa cotización expiró — por favor intenta de nuevo.',
    PMP00006: 'Ese monto está por debajo del mínimo del método de pago.',
    PMP00007: 'Ese monto excede el límite del método de pago.',
    POL00004: 'Esta transacción excede tu límite configurado. Contacta a un admin.',
    POL00007: 'Esta operación está esperando aprobación. Te avisaremos pronto.',
  };
  return userMessages[code] ?? 'Algo salió mal. Intenta de nuevo o contacta a soporte.';
}

function logError(error, context) {
  const apiError = error.response?.data ?? {};
  console.error(JSON.stringify({
    timestamp: new Date().toISOString(),
    ...context,
    statusCode: apiError.statusCode,
    errorCode: apiError.errorCode,
    message: apiError.message,
    path: apiError.path,
    apiTimestamp: apiError.timestamp,
  }));
}
 
try {
  await createPayoutOrder(token, orgId, merchantId, payoutData);
} catch (error) {
  logError(error, { operation: 'create_payout', merchantId });
  throw error;
}

class KoyweErrorHandler {
  constructor({ maxRetries = 3, logger = console } = {}) {
    this.maxRetries = maxRetries;
    this.logger = logger;
  }
 
  async execute(fn, context = {}) {
    for (let attempt = 0; attempt < this.maxRetries; attempt++) {
      try {
        return await fn();
      } catch (error) {
        this.logError(error, { ...context, attempt });
 
        if (!this.shouldRetry(error, attempt)) {
          throw this.formatError(error);
        }
 
        const delay = Math.pow(2, attempt) * 1000 + Math.random() * 500;
        await new Promise(r => setTimeout(r, delay));
      }
    }
  }
 
  shouldRetry(error, attempt) {
    if (attempt >= this.maxRetries - 1) return false;
    const status = error.response?.status;
    return (
      status === 408 ||
      status === 429 ||
      (status >= 500 && status < 600) ||
      error.code === 'ECONNABORTED'
    );
  }
 
  logError(error, context) {
    const apiError = error.response?.data ?? {};
    this.logger.error('Error de API Koywe:', {
      timestamp: new Date().toISOString(),
      ...context,
      errorCode: apiError.errorCode,
      statusCode: apiError.statusCode,
      message: apiError.message,
      path: apiError.path,
    });
  }
 
  formatError(error) {
    const apiError = error.response?.data;
    if (!apiError) return error;
    const err = new Error(apiError.message);
    err.errorCode = apiError.errorCode;
    err.statusCode = apiError.statusCode;
    err.path = apiError.path;
    return err;
  }
}
 
const errorHandler = new KoyweErrorHandler({ maxRetries: 3 });
const order = await errorHandler.execute(
  () => createPayinOrder(token, orgId, merchantId, orderData),
  { operation: 'create_payin', merchantId },
);

GET /api/v1/healthz

{ "status": "ok" }