Error Handling

{
  "code": 0,
  "error": "error message here"
}

{
  "message": "error message here"
}

{
  "code": 0,
  "error": "invalid credentials"
}

{
  "message": "missing value in request header"
}

{
  "message": "token is malformed: token contains an invalid number of segments"
}

{
  "code": 0,
  "error": "apiKey and apiSecret required"
}

{
  "code": 0,
  "error": "invalid payload"
}

{
  "code": 0,
  "error": "countryCode is required"
}

{
  "code": 0,
  "error": "countryCode must be one of: KE, TZ, UG, ZA"
}

{
  "code": 0,
  "error": "empty mobile number"
}

{
  "code": 0,
  "error": "phoneNumber must use the correct international prefix for the given countryCode"
}

{
  "code": 0,
  "error": "type must be \"paybill\" or \"till\""
}

{
  "code": 0,
  "error": "lipaNumber is required"
}

{
  "code": 0,
  "error": "receiverPhone is required"
}

{
  "code": 0,
  "error": "receiverLipaNumber is required"
}

{
  "code": 0,
  "error": "purposeOfTransfer must be one of: [family_support, education, business_payment, medical, investment, construction, rent, general, fuel, repairs, gift, personal_care, food_and_groceries, transport, travel, shopping, entertainment, donations, other]"
}

{
  "code": 0,
  "error": "sourceOfFunds must be one of: [salary, savings, business_income, sale_of_assets, investment_income, other]"
}

{
  "code": 0,
  "error": "from and to are required"
}

{
  "code": 0,
  "error": "rate USD_TZS not configured"
}

{
  "code": 0,
  "error": "rate USD_UGX not configured"
}

{
  "code": 0,
  "error": "rate USD_ZAR not configured"
}

{
  "code": 0,
  "error": "rate INVALID_KES not configured"
}

{
  "code": 0,
  "error": "transaction not found"
}

{
  "code": 0,
  "error": "duplicate reference"
}

{
  "code": 0,
  "error": "insufficient available balance"
}

{
  "code": 0,
  "error": "account not active"
}

{
  "code": 0,
  "error": "unsupported or malformed QR payload"
}

const response = await fetch("https://api.test.wakapay.io/business/balance", {
  headers: { Authorization: "Bearer YOUR_ACCESS_TOKEN" },
});
 
if (!response.ok) {
  const errorData = await response.json();
  console.error("Error " + response.status + ":", errorData);
  throw new Error(errorData.error || errorData.message);
}
 
const data = await response.json();
console.log("Success:", data);

async function makeRequestWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);
      const data = await response.json();
 
      if (response.ok) {
        return data;
      }
 
      // Don't retry on client errors (4xx except 429)
      if (
        response.status >= 400 &&
        response.status < 500 &&
        response.status !== 429
      ) {
        throw new Error(data.error || data.message);
      }
 
      // Retry on server errors (5xx) and rate limits (429)
      if (attempt < maxRetries) {
        const delay = Math.min(1000 * Math.pow(2, attempt), 10000);
        await new Promise((resolve) => setTimeout(resolve, delay));
        continue;
      }
 
      throw new Error(data.error || data.message);
    } catch (error) {
      if (attempt === maxRetries) {
        throw error;
      }
    }
  }
}

async function sendPayout(payoutData) {
  try {
    const response = await fetch("/business/payout/transfer", {
      method: "POST",
      headers: {
        Authorization: "Bearer YOUR_ACCESS_TOKEN",
        "Content-Type": "application/json",
      },
      body: JSON.stringify(payoutData),
    });
 
    const data = await response.json();
 
    if (!response.ok) {
      const errorMessage = data.error || data.message;
 
      switch (true) {
        case errorMessage.includes("insufficient available balance"):
          console.error("Insufficient balance - notify admin");
          throw new Error("Unable to process: insufficient funds");
 
        case errorMessage.includes("duplicate reference"):
          console.error("Duplicate reference detected");
          throw new Error("Transaction already exists");
 
        case errorMessage.includes("rate") &&
          errorMessage.includes("not configured"):
          console.error("FX rate not configured");
          throw new Error("Currency pair not supported");
 
        case errorMessage.includes("account not active"):
          console.error("Account not active - use test numbers in TESTENV");
          throw new Error("Recipient account not active");
 
        case errorMessage === "missing value in request header":
          console.error("Authentication required");
          throw new Error("Please authenticate");
 
        default:
          throw new Error(errorMessage);
      }
    }
 
    return data;
  } catch (error) {
    console.error("Payout failed:", error);
    throw error;
  }
}

function logError(error, context = {}) {
  const errorLog = {
    timestamp: new Date().toISOString(),
    error: error.message,
    context: context,
  };
 
  console.error("API Error:", JSON.stringify(errorLog, null, 2));
 
  // Send to error tracking service in production
  if (process.env.NODE_ENV === "production") {
    // errorTracker.captureException(error, { extra: context });
  }
}
 
try {
  await sendPayout(payoutData);
} catch (error) {
  logError(error, {
    operation: "sendPayout",
    reference: payoutData.businessReference,
    amount: payoutData.amount,
  });
}

function getUserFriendlyErrorMessage(error) {
  const errorMessage = error.message;
 
  const errorMap = {
    "insufficient available balance":
      "Unable to process payment due to insufficient funds. Please contact support.",
    "duplicate reference": "This transaction has already been processed.",
    "account not active":
      "Recipient account is not active. Please verify recipient details.",
    rate: "Currency conversion not available for this currency pair.",
    "transaction not found":
      "Transaction not found. Please check the reference.",
    "missing value in request header":
      "Authentication required. Please log in again.",
    "invalid credentials": "Invalid credentials. Please check your API keys.",
    "unsupported or malformed QR payload":
      "Invalid QR code. Please scan again.",
    "phoneNumber must use the correct international prefix":
      "Invalid phone number format. Use international format (e.g., +254700000001).",
    "countryCode must be one of":
      "Invalid country code. Supported: KE, TZ, UG, ZA.",
  };
 
  for (const [key, message] of Object.entries(errorMap)) {
    if (errorMessage.includes(key)) {
      return message;
    }
  }
 
  return "An error occurred. Please try again or contact support.";
}

curl -X POST https://api.test.wakapay.io/business/auth \
  -H "Content-Type: application/json" \
  -d '{"apiKey":"invalid","apiSecret":"wrong"}'
# Returns: {"code":0,"error":"invalid credentials"}

# Send same businessReference twice
curl -X POST https://api.test.wakapay.io/business/payout/transfer \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"businessReference":"SAME-REF-001",...}'
# Second call returns: {"code":0,"error":"duplicate reference"}

# Use non-test phone number
curl -X POST https://api.test.wakapay.io/business/payout/transfer \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"receiverPhone":"+254712345678",...}'
# Returns: {"code":0,"error":"account not active"}

curl "https://api.test.wakapay.io/business/rate?from=USD&to=TZS" \
  -H "Authorization: Bearer TOKEN"
# Returns: {"code":0,"error":"rate USD_TZS not configured"}