All SDK errors are IcpayError with a machine code and message.
import { Icpay, IcpayError } from '@ic-pay/icpay-sdk'
try {
await icpay.createPayment({ symbol: 'ICP', amount: '1000' })
} catch (e) {
if (e instanceof IcpayError) {
if (e.isBalanceError()) {
// prompt user to add funds
} else if (e.isNetworkError()) {
// retry or show offline UI
}
}
}
Error reference
| Code | Category | Description | What to do |
|---|---|---|---|
| WALLET_NOT_CONNECTED | Wallet | A wallet/principal is required but not connected (e.g., before calling createPayment). | Ask the user to connect their wallet; provide an actorProvider and connectedWallet. |
| WALLET_CONNECTION_FAILED | Wallet | Failed to connect to the selected wallet provider. | Offer retry or let the user pick another provider. |
| WALLET_DISCONNECTED | Wallet | Wallet was disconnected mid-flow. | Reconnect and restart the action. |
| WALLET_SIGNATURE_REJECTED | Wallet | User rejected the signature prompt. | Treat as user cancel; allow retry. |
| WALLET_USER_CANCELLED | Wallet | User cancelled the operation. | Do not show as an error; allow retry. |
| WALLET_PROVIDER_NOT_AVAILABLE | Wallet | Requested wallet provider not available in the environment. | Hide/disable unavailable providers; suggest alternatives. |
| UNSUPPORTED_PROVIDER | Wallet | The provider is not supported by the SDK. | Use a supported provider. |
| NO_PROVIDERS_AVAILABLE | Wallet | No wallet providers detected. | Prompt user to install/enable a wallet. |
| INSUFFICIENT_BALANCE | Balance | User balance on selected ledger is insufficient for the amount/fee. | Ask user to add funds or pick smaller amount. |
| BALANCE_CHECK_FAILED | Balance | Balance fetch could not complete. | Retry; ensure wallet principal and ledger canister ID are correct. |
| BALANCES_FETCH_FAILED | Balance | Failed to get all balances. | Retry or fetch single-ledger balance as a fallback. |
| SINGLE_BALANCE_FETCH_FAILED | Balance | Failed to get a specific ledger balance. | Retry; verify ledger canister ID and connection. |
| TRANSACTION_FAILED | Transaction | Generic failure sending funds or completing a step. | Show message and allow retry; log details. |
| TRANSACTION_TIMEOUT | Transaction | Timed out waiting for confirmation. | Show pending state and continue polling or allow retry. |
| TRANSACTION_CANCELLED | Transaction | Transaction was cancelled. | Treat similar to user-cancel. |
| TRANSACTION_INVALID | Transaction | Invalid transaction parameters or state. | Validate inputs; correct configuration or amount. |
| TRANSACTION_STATUS_FETCH_FAILED | Transaction | Could not fetch transaction status. | Retry with backoff; ensure canister/network is reachable. |
| TRANSACTION_SYNC_TRIGGER_FAILED | Transaction | Failed to trigger a sync from canister to API DB. | Retry later; the background sync may still complete. |
| SEND_FUNDS_USD_FAILED | Transaction | Failed when converting USD to token and sending. | Check price availability and retry. |
| NETWORK_ERROR | Network | Network connectivity problem. | Retry with backoff; show offline UI. |
| API_ERROR | Network | Server-side error from API. | Retry; if persistent, contact support and log details. |
| RATE_LIMIT_EXCEEDED | Network | Too many requests. | Back off and retry after delay. |
| INVALID_CONFIG | Config | Misconfigured SDK options. | Fix config (e.g., missing actor provider for send calls). |
| MISSING_PUBLISHABLE_KEY | Config | No publishable key provided for public operations. | Provide publishable key. |
| INVALID_PUBLISHABLE_KEY | Config | Provided publishable key is invalid. | Verify and replace key. |
| SECRET_KEY_REQUIRED | Config | Method requires secret key (server-side). | Move call to server and provide secretKey. |
| VALIDATION_ERROR | Config | Input validation failed. | Correct parameters and retry. |
| LEDGER_NOT_FOUND | Ledger | Ledger not found (by canister ID or symbol). | Verify canister ID/symbol; use getVerifiedLedgers(). |
| LEDGER_NOT_VERIFIED | Ledger | Ledger is not verified for usage. | Choose a verified ledger. |
| TOKEN_NOT_SUPPORTED | Ledger | Token/ledger not supported. | Use a supported ledger. |
| INVALID_LEDGER_SYMBOL | Ledger | Provided symbol is invalid. | Use a non-empty valid symbol. |
| LEDGER_SYMBOL_NOT_FOUND | Ledger | No verified ledger matches the symbol. | Inspect verified ledgers or correct symbol. |
| LEDGER_INFO_FETCH_FAILED | Ledger | Failed to fetch ledger info. | Retry; verify canister ID. |
| LEDGERS_WITH_PRICES_FETCH_FAILED | Ledger | Failed to fetch ledgers with price data. | Retry later. |
| VERIFIED_LEDGERS_FETCH_FAILED | Ledger | Failed to fetch verified ledgers. | Retry later. |
| ACCOUNT_NOT_FOUND | Account | Account not found. | Check account context/keys. |
| ACCOUNT_INACTIVE | Account | Account is inactive. | Reactivate or contact support. |
| ACCOUNT_INFO_FETCH_FAILED | Account | Failed to fetch account info. | Retry; verify keys. |
| ACCOUNT_WALLET_BALANCES_FETCH_FAILED | Account | Failed to fetch account wallet balances. | Retry later. |
| INVALID_USD_AMOUNT | Price | USD amount <= 0 for conversion. | Provide a positive amount. |
| PRICE_NOT_AVAILABLE | Price | No price available for the selected ledger. | Pick a priced ledger or try later. |
| PRICE_CALCULATION_FAILED | Price | Failed to compute token amount from USD. | Retry; verify price availability. |
| TRANSACTION_HISTORY_FETCH_FAILED | History | Failed to fetch transactions history. | Retry; verify filters. |
| PAYMENT_HISTORY_FETCH_FAILED | History | Failed to fetch payment history. | Retry; verify filters. |
| PAYMENTS_BY_PRINCIPAL_FETCH_FAILED | History | Failed to fetch payments by principal. | Retry; verify principal and filters. |
| UNKNOWN_ERROR | Generic | Unclassified error. | Show generic message; log details for diagnosis. |