Error Handling and the MethodReturn Pattern Reference

How the VivaWallet SDK reports errors: the MethodReturn discriminated union, known error codes, and handling unexpected network exceptions.

Every async method in the SDK returns a MethodReturn<TData, TCode> discriminated union — it never throws for API errors. Always check result.success before accessing result.data.

Do not access result.data without first checking result.success. On failure, data is always null, which will cause a runtime error if you attempt to destructure or read properties from it.

---

The MethodReturn Pattern

The MethodReturn<TData, TCode> type resolves to one of two shapes:

// Success
{ success: true;  data: TData; message: string }

// Failure
{ success: false; data: null;  message: string; code: TCode }

Check the success flag first, then TypeScript narrows the type automatically:

const result = await vivawallet.payments.createOrder({ ... });

if (!result.success) {
  // Handle error
  console.error('Error code:', result.code);
  console.error('Message:', result.message);
  return;
}

// Safe to use result.data here
const { orderCode } = result.data;

This pattern is consistent across all three clients (Vivawallet, VivaISV, Marketplace) and every sub-client module.

---

Known Error Codes

The code field on a failure response is typed as a string literal so you can exhaustively handle specific conditions.

Code	Context	Meaning
webhookerror	Webhook operations (webhooks.retrieveWebhookKey(), deprecated getVivaWebhookCode())	Failed to retrieve or verify the webhook key — either the API request failed or the response contained no key.

Most error codes are specific to the underlying VivaWallet API call. The message field always contains the human-readable API error detail, which is the most reliable source for debugging any unexpected failure code.

---

Handling Network and HTTP Errors

The SDK uses axios internally. HTTP error responses from the VivaWallet API (4xx / 5xx status codes) are caught by the SDK and translated into a { success: false, message, code } failure response — you do not need to wrap SDK calls in try/catch to handle normal API errors.

// No try/catch needed for API errors
const result = await vivawallet.transactions.getTransactionById('txn-id');

if (!result.success) {
  // API returned an error — result.message contains the detail
  console.error(result.message);
}

However, unexpected errors — such as a complete network outage, DNS failure, or misconfigured axios instance — may still result in an unhandled thrown exception. If your application needs to be resilient to infrastructure-level failures, wrap SDK calls in a try/catch:

try {
  const result = await vivawallet.payments.createOrder({ ... });
  if (!result.success) {
    // Normal API failure — handle gracefully
  }
} catch (err) {
  // Unexpected network-level error
  console.error('Unexpected error:', err);
}

---

Debugging Tips

• Log result.message — this field contains the human-readable error description returned by the VivaWallet API and is the fastest path to understanding what went wrong.
• Check your credentials — authentication-related errors (401/403) usually mean your clientId, clientSecret, merchantId, or apikey is incorrect or has been regenerated in the dashboard.
• Use dev: true with demo credentials — initialize the SDK client with dev: true for demo endpoints, and pass dev: true to getSmartCheckout() when generating a demo Smart Checkout URL.
• Verify your source code — many payment order failures are caused by a source code that does not exist or is not correctly configured. Confirm the source code is active in your VivaWallet dashboard under Sales → Payment Sources.