Error Reference

Understand Rain SDK error codes, their causes, and how to handle them on iOS and Android.

Both SDKs return consistent error codes, allowing you to implement the same error handling behavior across platforms. Errors are exposed as RainError on both platforms: an enum on iOS and a sealed class hierarchy in com.rain.sdk.error on Android.

Errors originating from Rain’s wallet infrastructure or external wallet providers are mapped to Rain error codes before reaching your application.

Handle SDK errors

Each error has a code and an associated error type. Use the error type to determine how your application responds and the error code for consistent logging and support.\

iOS

do {
    let result = try await client.sendToken(chainId: chainId, contractAddress: usdc, to: recipient, amount: amount)
} catch let error as RainError {
    switch error {
    case .insufficientTokenBalance(let requested, let available, let token):
        show("You have \(available) \(token); \(requested) needed.")
    case .transactionPending(let statusId):
        pollLater(statusId)                     // accepted; the hash is still on its way
    case .tokenExpired:
        showLoginScreen()
    default:
        show(error.errorDescription ?? error.code)        // code is "RAIN_xxx"
    }
}

Multiple errors may share the same code when they require similar handling. For example, RAIN_102 covers configuration and input errors, while RAIN_402 covers insufficient balances.

Use the error type and associated details to provide specific feedback to users.

Configuration errors

Errors related to SDK initialization, provider configuration, invalid inputs, and unsupported networks.

Code	iOS case / Android class	Cause	Recommended action
RAIN_101	sdkNotInitialized / SdkNotInitialized	A wallet operation was called before the SDK client finished initializing.	Resolve the client using rain.provider(...) before making wallet requests.
RAIN_102	invalidConfig(details:) / InvalidConfig	Invalid configuration or input, including missing contact information, improperly formatted phone numbers, invalid passkeys, or conflicting provider registration.	Inspect the error details and correct the configuration or input.
RAIN_102	providerNotRegistered(details:) / ProviderNotRegistered	An operation references a wallet provider that has not been registered.	Register the provider before calling build().
RAIN_102	tokenNotFound(token:chainId:) / TokenNotFound	The token contract could not be found on the specified network, or its decimals could not be determined.	Verify the token address and network. Register the token using registerTokens if necessary.
RAIN_102	invalidRecipient(address:reason:) / InvalidRecipient	The recipient address is invalid, incompatible with the selected network, or references the token’s own contract or mint.	Display the returned reason next to the recipient address field.
RAIN_103	invalidRpcUrl(_:) / InvalidRpcUrl	The configured RPC endpoint is not a valid URL.	Correct the RPC endpoint in your SDK configuration.
RAIN_104	chainNotSupported(chainId:details:) / ChainNotSupported	The requested operation is not supported on the selected network or by the configured wallet provider.	Disable unsupported operations for that network. See Blockchain support.

Authentication errors

Errors related to authentication, expired sessions, and invalid login credentials.

Code	iOS case / Android class	Cause	Recommended action
RAIN_201	tokenExpired / TokenExpired	The user has no active session, the session has expired, or the session could not be refreshed.	Return the user to authentication. For external wallet providers, check the session refresh callback.
RAIN_202	unauthorized / Unauthorized	The wallet infrastructure rejected the request’s credentials.	Reauthenticate the user. Contact Rain if the issue persists.
RAIN_203	invalidLoginCode / InvalidLoginCode	The authentication code is incorrect, expired, or has already been used.	Allow the user to retry. Follow the configured resend and retry limits.

Network errors

Errors related to network connectivity and transaction processing.

Code	iOS case / Android class	Cause	Recommended action
RAIN_301	networkError(underlying:) / NetworkError	The RPC endpoint or wallet infrastructure is unavailable or the request timed out.	Retry read operations. For sends, treat the outcome as unknown: the transaction may have been submitted, and history lists confirmed transactions only. Keep the send pending and reconcile against history and the balance before allowing another send.
RAIN_302	transactionPending(statusId:) / TransactionPending	Rain accepted the transaction, but its hash was not available before the SDK polling window ended.	Display a pending transaction and refresh history. Retain statusId for support and avoid submitting the transaction again.

Transaction errors

Errors related to transaction validation, signing, insufficient balances, and collateral withdrawals.

Code	iOS case / Android class	Cause	Recommended action
RAIN_401	userRejected / UserRejected	The user canceled the signing request or a wallet provider’s confirmation prompt.	Return to the previous screen. No retry is necessary unless the user initiates another transaction.
RAIN_402	insufficientFunds(required:available:) / InsufficientFunds	The wallet lacks sufficient native tokens to cover the transfer amount or applicable fees. With gas sponsorship enabled, this primarily applies to native asset transfers and Solana rent.	Display the required amount, available balance, and shortfall.
RAIN_402	insufficientTokenBalance(requested:available:token:) / InsufficientTokenBalance	The wallet does not hold enough of the requested token to complete the transfer.	Display the available token balance and required amount.
RAIN_402	tokenAccountNotFound(walletAddress:token:) / TokenAccountNotFound	The wallet has never received the requested Solana token and has no associated token account.	Treat the token balance as zero.
RAIN_403	transactionSimulationFailed(underlying:) / TransactionSimulationFailed	Transaction simulation indicates the transaction would fail. For sponsored transactions, this error may occur after signing.	Inspect the underlying error before allowing another attempt. Common causes include paused tokens and contract restrictions.
RAIN_404	walletUnavailable / WalletUnavailable	The wallet provider did not return a wallet address.	For Rain embedded wallets, prompt the user to log in again. For external providers, confirm that wallet creation is complete.
RAIN_405	withdrawalRevertedByNetwork / WithdrawalRevertedByNetwork	A collateral withdrawal was rejected onchain, commonly because a previously issued admin signature was reused after the available withdrawal amount changed.	Request a new admin signature and retry the withdrawal once. See Card funding and settlement.
RAIN_406	invalidAmount(amount:reason:) / InvalidAmount	The amount is negative, cannot be represented, or exceeds the token’s supported decimal precision.	Validate the amount against the token’s decimals. Display the returned reason when available.
RAIN_407	walletNotAuthorized(walletAddress:proxyAddress:) / WalletNotAuthorized	The signing wallet is not authorized to withdraw from the collateral contract.	Verify that the wallet address matches the contract owner. If necessary, update the registered owner wallet. See Changing the owner wallet.

Provider and internal errors

Errors originating from wallet providers or unexpected SDK states.

Code	iOS case / Android class	Cause	Recommended action
RAIN_501	providerError(underlying:) / ProviderError	An error occurred in Rain’s wallet infrastructure or an external wallet provider and could not be mapped to a more specific error.	Log the error code and underlying details. Contact Rain if the issue persists.
RAIN_502	internalError(details:) / InternalError	The SDK encountered an unexpected internal state, such as a malformed signature, an EIP 712 encoding failure, or a configuration operation being applied twice.	Contact Rain support with the error code and associated details.

Troubleshooting

Common integration issues and how to resolve them when using Rain’s embedded wallet SDKs.

Every SDK call returns RAIN_201 after app launch

The SDK may be attempting to resolve the wallet client before the user’s saved session has been restored. Call awaitSessionRestore() on the provider, then check hasActiveSession() before resolving the client.

Sending on Avalanche returns RAIN_104

Avalanche supports balance retrieval and transaction history, but outbound transactions are not currently supported through Rain embedded wallets. Disable sending for unsupported networks. For card funding, use a supported network such as Base or Arbitrum. If your application broadcasts transactions independently, prepareWithdrawal can still prepare and sign collateral withdrawals without broadcasting them through Rain.

Sponsored transactions return RAIN_403 after a delay

Sponsored transactions skip local simulation because wallets without native tokens could otherwise fail the simulation before sponsorship is applied. As a result, transaction failures may surface after signing, when Rain’s wallet infrastructure processes the transaction. Inspect the underlying error to determine why the transaction reverted. Do not automatically retry without identifying the cause.

An incorrect login code logs the user out

RAIN_203 indicates an invalid, expired, or previously used authentication code. It should not terminate the user’s session or clear the pending authentication challenge. Keep the user on the authentication screen and allow them to retry. Make sure your application handles RAIN_203 separately from authentication errors that require a new login.

A previously working wallet returns RAIN_407 during collateral withdrawal

The wallet attempting to sign the withdrawal may no longer match an authorized administrator on the collateral contract. This can occur if the user creates a new account with different login credentials or the wallet address associated with their application changes. Compare the address returned by getWalletAddress() with the contract’s adminAddresses, retrieved using GET /v1/issuing/users/{userId}/contracts.

Wallet balances appear without token symbols

The token may not be included in Rain’s token registry. On Solana, token mints do not provide symbols directly onchain. Register the token using registerTokens and supply its metadata, including its address, symbol, decimals, and name. This allows the SDK to display consistent token information across your application.

What’s next

Testing

Reproduce these errors safely on testnets.

Sending funds

How sends, fees, and pending states behave.