> For AI agents: the documentation index is at https://sdk.nimbusprivacy.xyz/llms.txt, and every page is available as Markdown at its URL with .md appended.

# Errors (/helpers/errors)

Most of what your user can cause comes back as a result, such as `declined`. The SDK throws only
when your app usually cannot fix things by asking the user. It throws one of two errors:

| Error                   | What it means                                                                   | Guard                     |
| ----------------------- | ------------------------------------------------------------------------------- | ------------------------- |
| `NimbusSdkError`        | The SDK could not go on: a setting, the browser, the wallet or a service.       | `isNimbusSdkError`        |
| `NimbusSolanaFlowError` | The protocol refused the payment, such as an amount too small to cover the fee. | `isNimbusSolanaFlowError` |

Each carries a `reason`. Compare the reason, never the message. The message is for your logs.

## Catch them

Use the guards, not `instanceof`. A guard still works when your bundle holds two copies of the SDK.

```ts
import {
  deposit,
  isNimbusSdkError,
  isNimbusSolanaFlowError,
} from "@umbra/nimbus-solana-web";

try {
  await deposit(context, { mint: usdc, amount: 5_000_000n, recipient: bob });
} catch (thrown) {
  if (isNimbusSolanaFlowError(thrown)) {
    console.error(thrown.reason, thrown.detail);
    showError("The payment was refused. Check the amount and the recipient.");
  } else if (isNimbusSdkError(thrown)) {
    console.error(thrown.reason, thrown.message);
    showError("Something went wrong. Try again in a moment.");
  } else {
    throw thrown;
  }
}
```

Rethrow anything neither guard knows. It is a bug in your app or in the SDK, not a refusal.

A `NimbusSolanaFlowError` also carries `detail`, the names and counts that locate the refusal. It
never holds keys, so it is safe to log.

[Results and errors](https://sdk.nimbusprivacy.xyz/api-design/results-and-errors) lists every reason of both errors, with what to
do about each.

## Next

- [Results and errors](https://sdk.nimbusprivacy.xyz/api-design/results-and-errors): Every reason, and what to do about it.
- [Troubleshooting](https://sdk.nimbusprivacy.xyz/production/troubleshooting): Fixes for the errors developers meet most.
- [API reference](https://sdk.nimbusprivacy.xyz/reference/errors): NimbusSdkError and the two guards.


Last updated 21 October 2026