> ## Documentation Index
> Fetch the complete documentation index at: https://vivawallet-sdk-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`.

<Warning>
  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.
</Warning>

***

## The MethodReturn Pattern

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

```typescript theme={null}
// 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:

```typescript theme={null}
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. |

<Note>
  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.
</Note>

***

## 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.

```typescript theme={null}
// 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`:

```typescript theme={null}
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**.