Error Handling

{
  "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;
 
      // Exponential backoff with 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;
 
  // Poll until approval resolves — the CLI's `flow order --wait` does this
  // for you. Production integrations should listen to webhooks instead of
  // polling (see "Webhooks deep dive").
  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(`Order ${order.id} still ON_HOLD after 5 minutes`);
}

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 payment method available for this country/currency');
}

function translateErrorToUser(error) {
  const code = error.response?.data?.errorCode;
  const userMessages = {
    BAA00014: "We don't have enough balance to complete this payout right now.",
    DC00010: 'Please double-check the document number.',
    QE00003: 'That price quote has expired — please try again.',
    PMP00006: 'That amount is below the minimum for this payment method.',
    PMP00007: 'That amount exceeds the limit for this payment method.',
    POL00004: 'This transaction exceeds your configured limit. Please contact an admin.',
    POL00007: 'This operation is waiting for approval. You\'ll be notified shortly.',
  };
  return userMessages[code] ?? 'Something went wrong. Please try again or contact support.';
}

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('Koywe API error:', {
      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" }