Error Handling

{
  "type": "https://errors.zuba.com/business-decline/payout-not-cancellable",
  "title": "The payout can no longer be cancelled",
  "status": 409,
  "detail": "A payout in status 'processing' cannot be cancelled",
  "code": "PAYOUT_NOT_CANCELLABLE",
  "category": "BUSINESS_DECLINE",
  "request_id": "3f9d2b6e-1c47-4a58-9e0b-7a12c4d8f631",
  "retryable": false,
  "instance": "/v1/payouts/8b1d4a9e-2f3c-4d5e-9a0b-1c2d3e4f5a6b/cancel"
}

{
  "statusCode": 404,
  "message": "Payout not found",
  "error": "Not Found",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "path": "/v1/payouts/8b1d4a9e-2f3c-4d5e-9a0b-1c2d3e4f5a6b"
}

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Insufficient balance",
  "code": "INSUFFICIENT_BALANCE",
  "detail": "Insufficient balance to cover the debit, including fees.",
  "timestamp": "2026-01-15T10:30:00.000Z",
  "path": "/v1/payouts"
}

// A legacy rejection carries its stable code in `code` or, for most codes, as `message`.
const LEGACY_CODE = /^[A-Z][A-Z0-9_]*$/;

class ZubaAPIError extends Error {
  constructor(status, body) {
    super(body.detail || body.message || `HTTP ${status} error`);
    this.name = 'ZubaAPIError';
    this.status = status;
    this.code = body.code ?? (LEGACY_CODE.test(body.message) ? body.message : undefined);
    this.category = body.category;
    this.retryable = body.retryable === true;
    this.requestId = body.request_id;
    this.details = body.details;              // validation errors (400)
  }
}

async function handleZubaResponse(response) {
  if (response.ok) {
    return await response.json();
  }
  const body = await response.json().catch(() => ({}));
  throw new ZubaAPIError(response.status, body);
}

function handlePayoutError(error) {
  switch (error.code) {
    case 'INSUFFICIENT_BALANCE':
      // Fund the balance or reduce the amount, then send it as a new payout
      // with a new clientRef; do not resubmit unchanged.
      return { action: 'TOPUP_BALANCE', retry: false };

    case 'RECIPIENT_DETAILS_INVALID':
      // Fix the beneficiary's details, then submit a new payout.
      return { action: 'UPDATE_BENEFICIARY', retry: false };

    case 'LIMIT_EXCEEDED':
      // Contact your account manager about limits. Amounts above corridor
      // caps are served by the orders channel (see /guides/orders).
      return { action: 'CONTACT_ACCOUNT_MANAGER', retry: false };

    case 'IDEMPOTENCY_KEY_PROCESSING':
      // The first request with this key is still in flight:
      // retry the identical request to receive its response.
      return { action: 'RETRY_SAME_REQUEST', retry: true };

    default:
      return { action: error.retryable ? 'RETRY_LATER' : 'CONTACT_SUPPORT', retry: error.retryable };
  }
}

{
  "statusCode": 400,
  "error": "BAD_REQUEST",
  "message": "senderInfo.phoneNumber is required for XAF payouts to Cameroon (international format, e.g. +237650000000); senderInfo.gender is required for XAF payouts to Cameroon (M or F)",
  "details": [
    {
      "field": "senderInfo.phoneNumber",
      "code": "SENDER_INFO_INCOMPLETE",
      "message": "senderInfo.phoneNumber is required for XAF payouts to Cameroon (international format, e.g. +237650000000)"
    },
    {
      "field": "senderInfo.gender",
      "code": "SENDER_INFO_INCOMPLETE",
      "message": "senderInfo.gender is required for XAF payouts to Cameroon (M or F)"
    }
  ],
  "timestamp": "2026-01-15T10:30:00.000Z",
  "path": "/v1/payouts"
}

const PRODUCTION_CURRENCIES = ['EUR', 'USD', 'GBP', 'USDC', 'USDT', 'EURC', 'NGN', 'XOF', 'XAF', 'GHS', 'KES', 'UGX'];
const ROUTES = ['bank_transfer', 'ach', 'fedwire', 'swift', 'crypto', 'mobile_money'];

function validatePayout(payout) {
  const errors = [];

  // clientRef: required, unique per payout, max 100 characters
  if (!payout.clientRef || payout.clientRef.length > 100) {
    errors.push('clientRef is required (max 100 characters, unique per payout)');
  }

  // amount: positive decimal string with up to 8 decimal places
  if (!/^\d+(\.\d{1,8})?$/.test(payout.amount ?? '') || Number(payout.amount) <= 0) {
    errors.push('amount must be a positive decimal string with up to 8 decimal places');
  }

  if (!PRODUCTION_CURRENCIES.includes(payout.currency)) {
    errors.push(`currency must be one of: ${PRODUCTION_CURRENCIES.join(', ')}`);
  }

  // Reference an existing beneficiary by id
  if (!payout.beneficiary?.id) {
    errors.push('beneficiary.id is required');
  }

  // route is optional: when set, it must be a live route
  if (payout.route && !ROUTES.includes(payout.route)) {
    errors.push(`route must be one of: ${ROUTES.join(', ')}`);
  }

  return errors;
}

async function createPayoutWithRetry(payout, { maxAttempts = 4, baseDelayMs = 1000 } = {}) {
  const idempotencyKey = crypto.randomUUID();

  for (let attempt = 1; ; attempt++) {
    try {
      const response = await fetch('https://api.zuba.com/v1/payouts', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'Authorization': 'Bearer YOUR_API_KEY',
          'Idempotency-Key': idempotencyKey
        },
        body: JSON.stringify(payout)
      });
      return await handleZubaResponse(response);
    } catch (error) {
      // Branch on the envelope's retryable flag, not on status-code heuristics.
      // Network errors are safe to retry because the key deduplicates them.
      const retryable = error instanceof ZubaAPIError ? error.retryable : true;

      if (!retryable || attempt >= maxAttempts) {
        throw error;
      }

      const delay = baseDelayMs * 2 ** (attempt - 1) * (1 + Math.random() * 0.1);
      await new Promise((resolve) => setTimeout(resolve, delay));
    }
  }
}

const PAYOUT_TERMINAL_STATUSES = ['paid', 'failed', 'cancelled'];

async function waitForPayout(payoutId, { intervalMs = 5000, timeoutMs = 300000 } = {}) {
  const deadline = Date.now() + timeoutMs;
  let lastStatus = 'unknown';

  while (Date.now() < deadline) {
    const response = await fetch(`https://api.zuba.com/v1/payouts/${payoutId}`, {
      headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
    });
    const payout = await handleZubaResponse(response);
    lastStatus = payout.status;

    if (PAYOUT_TERMINAL_STATUSES.includes(payout.status)) {
      return payout;
    }

    await new Promise((resolve) => setTimeout(resolve, intervalMs));
  }

  throw new Error(`Payout ${payoutId} still in flight after ${timeoutMs}ms (last status: ${lastStatus})`);
}