Error handling

The Portal Android SDK uses a structured PortalException hierarchy so you can catch errors at the granularity you need — from individual error cases up to broad categories. Errors the SDK raises itself are subclasses of PortalException, which itself extends Exception. Network and transport failures — including timeouts — propagate as the underlying IOException, and argument or state checks can throw IllegalArgumentException or IllegalStateException, so don’t rely on catch (e: PortalException) alone.

Exception hierarchy

PortalException is a sealed class with ten category-level sealed subclasses:

Category	Description
`PortalException.Mpc`	MPC key generation, backup, recovery, and signing operations
`PortalException.Storage`	Google Drive, Passkey, and Keychain storage operations
`PortalException.Wallet`	Wallet state and availability
`PortalException.Transaction`	Transaction building and asset transfers
`PortalException.Api`	HTTP requests, RPC calls, and API errors
`PortalException.Connect`	PortalConnect (WalletConnect) operations
`PortalException.Provider`	Provider request routing and validation
`PortalException.Blockchain`	Chain ID parsing and namespace resolution
`PortalException.Credentials`	Resolving a `Portal` instance’s credential into a bearer token
`PortalException.Auth`	Client Auth sign-in flows raised by `PortalAuth`

Catching exceptions

Because the hierarchy is sealed, you can catch at any level of specificity.

Catch a specific exception

try {
    portal.backupWallet(backupMethod = BackupMethods.Passkey)
} catch (e: PortalException.Mpc.BackupMethodNotConfigured) {
    println("Passkey backup is not configured: ${e.message}")
} catch (e: PortalException.Storage.PasskeyNotSupported) {
    println("This device does not support passkeys: ${e.message}")
}

Catch an entire category

try {
    portal.backupWallet()
} catch (e: PortalException.Mpc) {
    println("MPC operation failed: ${e.message}")
} catch (e: PortalException.Storage) {
    println("Storage operation failed: ${e.message}")
}

Catch any Portal exception

try {
    portal.createWallet().getOrThrow()
} catch (e: PortalException) {
    println("Portal error: ${e.message}")
}

Handle errors from `Result`-returning methods

Some methods like sendAsset return a Result instead of throwing. Use onFailure or exceptionOrNull() to inspect the error:

portal.sendAsset(
    chainId = "eip155:11155111",
    params = SendAssetParams(to = "0x...", amount = "0.01", token = "NATIVE")
).onSuccess { txHash ->
    println("Transaction sent: $txHash")
}.onFailure { e ->
    when (e) {
        is PortalException.Transaction.SendAssetArgumentError ->
            println("Invalid parameters: ${e.message}")
        is PortalException ->
            println("Portal error: ${e.message}")
        else ->
            println("Unexpected error: ${e.message}")
    }
}

Branch on the HTTP status code

PortalException.Api.HttpRequestFailed exposes the status code that produced the failure, so you can separate a transient server-side error from a terminal one without matching on the message string.

Property	Type	Description
`statusCode`	`Int?`	The HTTP status code that produced the failure, or `null` when the SDK captured no status code.

HttpRequestFailed only covers status codes that aren’t already routed to a more specific exception: 4xx codes of 402 and above, every 5xx, and unrecognized codes. One exception: when the Enclave MPC API responds 409 or 422 with a Portal error id in the body, the SDK throws PortalException.Mpc.MpcResultError with that id instead (starting from SDK version 10.1.0). A 400 throws PortalException.Api.HttpBadRequest and a 401 throws PortalException.Api.HttpUnauthorized, both of which are siblings of HttpRequestFailed rather than subclasses. statusCode is therefore never 400 or 401 — catch those two types directly. The whole 2xx range is a success. A 201 or 202 returns its body like a 200 does, and a 204 returns an empty string.

Earlier versions treated only 200 and 204 as successes. Any other 2xx — a 201 from a resource-creating endpoint, say — threw HttpRequestFailed and discarded the body it had just returned. If you have a catch that treats HttpRequestFailed with a 2xx statusCode as an expected outcome, it is now unreachable.

statusCode is null in two situations, and neither one means “unknown error”:

No HTTP response was received. A socket timeout, a DNS failure, or a malformed status line never produces a status code. Codes outside the 100..599 range are reported as null for the same reason.
The request returned 200 OK but the body carried an error envelope. The failure is real, but the HTTP status was a success, so there is no error code to report.

Treat null as “there is no status code to branch on” and fall through to your default handling:

portal.api.getAssets(chainId)
    .onSuccess { assets ->
        println("Assets: $assets")
    }
    .onFailure { error ->
        when (error) {
            is PortalException.Api.HttpBadRequest ->
                println("Invalid request: ${error.rawBody}")
            is PortalException.Api.HttpUnauthorized ->
                println("Unauthorized — check your Portal API key")
            is PortalException.Api.HttpRequestFailed -> when {
                error.statusCode == null ->
                    println("No status code: network failure or error envelope")
                error.statusCode in 500..599 ->
                    println("Transient server error ${error.statusCode} — retry with backoff")
                else ->
                    println("Request failed with HTTP ${error.statusCode}")
            }
            else ->
                println("Unexpected error: ${error.message}")
        }
    }

statusCode was added in 9.1.0. On earlier versions the only way to identify the status code was to parse it out of message, which is formatted as "<statusCode> - <responseBody>".

Request timeouts

Every HTTP request the SDK makes is bounded. A host that accepts the connection and then never answers fails the call instead of suspending it.

Timeout	Default	Applies to
Connect	30 seconds	Establishing the connection, on every request.
Read	60 seconds	Waiting for response data, on every request.
Read (enclave MPC)	120 seconds	Enclave MPC operations, which do real cryptographic work server-side and legitimately take longer.

A timeout surfaces as a java.net.SocketTimeoutException, propagated unwrapped like every other transport failure — it is not a PortalException, so a catch (e: PortalException) will not see it, and a Result-returning method carries the raw exception in its failure. Catch IOException alongside the Portal types:

import java.io.IOException
import java.net.SocketTimeoutException

try {
    val client = portal.api.getClient()
} catch (e: SocketTimeoutException) {
    // The request was bounded and gave up. Safe to retry with backoff.
    println("Portal did not respond in time — retrying")
} catch (e: IOException) {
    println("Network failure: ${e.message}")
} catch (e: PortalException) {
    println("Portal error: ${e.message}")
}

To change the limits, construct a PortalRequests and pass it to Portal:

import io.portalhq.android.utils.PortalRequests

val portal = Portal(
    apiKey = YOUR_CLIENT_API_KEY,
    requests = PortalRequests(
        connectTimeoutMs = 15_000,
        readTimeoutMs = 90_000,
    ),
)

Timeouts were added in 10.0.0. Before that both defaulted to HttpURLConnection’s 0, meaning infinite: a request to a host that accepted the connection and stopped responding never returned, and never threw. If you added your own watchdog around Portal calls to work around that, you can now rely on the SDK’s own limits — though note that a withTimeout around a suspending Portal call still will not cancel the underlying socket read, which is why the bound has to live in the transport.

The read timeout applies per request, not per operation. A multi-step flow such as sendAsset, backupWallet or recoverWallet makes several requests and can legitimately run longer than 60 seconds end to end without any single request timing out.

Absent shares versus unreadable shares

As of 9.1.0, having no share on the device is no longer an error. getShares() on a Keychain instance returns null in that case; before 9.1.0 it threw IllegalArgumentException("No user share found on device storage"). getShares() reads through a fallback chain: the current shares key first, then three legacy key formats kept for backward compatibility. An entry that can’t be parsed doesn’t fail the call — it moves on to the next format in the chain. So an unreadable entry under the current shares key resolves to null too, as long as no legacy entry is readable either.

Situation	Before `9.1.0`	`9.1.0` and later
No share on the device	throws `IllegalArgumentException`	returns `null`
Unreadable entry under the current `shares` key, no readable legacy entry	throws `IllegalArgumentException`	returns `null`
Unreadable entry under the deprecated `PortalMpc.DgkResult` key	throws `IllegalArgumentException`	throws, message `"Unable to parse share from device storage"`

Treat a null result as “this device has no usable share” rather than strictly “no share exists”. Code that relied on the throw to detect “no wallet on this device” will now take the success path with a null value instead of entering its catch block, so check the result for null explicitly.

The "Unable to parse share from device storage" message is reserved for the last link in that chain — the misspelled deprecated key from an older SDK version — so in practice you’ll only see it on a device mid-migration. A parse failure elsewhere in the chain surfaces as whatever the JSON parser threw, not as an IllegalArgumentException. This is what makes portal.isWalletOnDeviceOrThrow() return false rather than throw when the user has no usable wallet on the current device. See manage wallet lifecycle states for the migration.

Exception reference

MPC (`PortalException.Mpc`)

Exception	Description
`BackupShareNotFound`	No backup share found for the specified backup method.
`OrganizationBackupShareNotFound`	No organization backup share found for the specified backup method.
`WalletNotFound`	No wallet found for the specified backup method.
`MpcVersionNoLongerSupported`	The MPC operation is not supported on the current MPC version. Upgrade to `v6`.
`WalletModificationAlreadyInProgress`	Another wallet modification operation (generate, backup, recover) is already running.
`MpcResultError`	The MPC server returned an error. Exposes `id` (the error identifier string) and `error` (a `PortalError` with `id` and `message`). See MPC error codes for the full list of server-side error IDs. When Portal rejects a repeated idempotency key, `error.isIdempotencyRejection()` returns `true`. Starting from SDK version 10.1.0, this also covers Enclave MPC API `409` and `422` responses that carry an error `id`.
`UnableToDeriveShareId`	Could not derive a share ID from the generated share.
`UnableToReadShares`	Failed to read shares from storage.
`BackendStorageFailed`	Failed to store data on Portal’s backend.
`ClientCipherTextNotFound`	No client cipherText found for the specified backup method during recovery.
`UnableToReadFromBackupStorage`	Failed to read data from backup storage.
`UnableToReadFromKeychain`	Failed to read data from keychain storage.
`UnableToNotifyEjection`	Could not notify Portal of the ejection request.
`NoPrivateKeysEjected`	No private keys could be ejected.
`ShareFormattingError`	Error formatting shares during ejection.
`NoFormattedSharesData`	No data found in the formatted shares response.
`InstanceNotAvailable`	The MPC instance is not available.
`BackupMethodNotConfigured`	The specified backup method has not been configured on the Portal instance. See back up a wallet for configuration steps.
`UnsupportedCurve`	The specified cryptographic curve is not supported.
`Eip155WalletNotFound`	No EIP-155 wallet found. Call `createWallet()` first.

Storage (`PortalException.Storage`)

Exception	Description
`GoogleDriveWriteFailed`	Failed to write to Google Drive.
`GoogleDriveVerificationFailed`	Could not verify the file was saved to Google Drive.
`GoogleDriveFilenameError`	Cannot determine filename without a configured API.
`GoogleDriveClientDataUnavailable`	Client data is not available for Google Drive operations.
`GoogleDriveHashesError`	Error retrieving hashes from Google Drive.
`PasskeySessionIdNotFound`	No session ID found during passkey operations.
`PasskeyOperationError`	A passkey operation failed.
`KeychainValidationError`	Keychain validation failed.
`UserRecoverableGDriveException`	A user-recoverable Google Drive authentication error.
`StorageAuthError`	Storage authentication failed.
`PasskeyNotSupported`	Passkeys are not supported on this device.
`PasskeyStorageNotConfigured`	Passkey storage has not been configured on the Portal instance.

Wallet (`PortalException.Wallet`)

Exception	Description
`WalletNotOnDevice`	No wallet share is available on device storage. The user needs to recover their wallet. See wallet lifecycle states for handling this proactively.
`InvalidWalletState`	The wallet is in an invalid state for the requested operation.

Transaction (`PortalException.Transaction`)

Exception	Description
`InvalidTransactionResponse`	The response from the transaction was an unexpected type.
`SendAssetArgumentError`	Invalid arguments passed to `sendAsset` (missing parameters, invalid chain ID format, or unsupported namespace).

API (`PortalException.Api`)

Exception	Description
`HttpBadRequest`	An HTTP request returned 400 Bad Request. Exposes `rawBody`, the unparsed response body.
`YieldApiBadRequest`	The Yield API returned a 400 Bad Request error. Extends `HttpBadRequest`.
`HttpRequestFailed`	An HTTP request failed with a non-success status code other than 400 or 401. Exposes `statusCode` — see branch on the HTTP status code.
`RpcError`	An RPC request failed. Contains `code` and `message` fields.
`HttpUnauthorized`	An HTTP request returned 401 Unauthorized. Check your API key. A 401 also retires the credential behind the `Portal` that made the request — see the note below.

A 401 on a request that carried Portal’s bearer token also retires the credential behind the Portal instance that made the request, and fires that instance’s onSessionInvalidated() listeners. This changes nothing for a Portal built from a Client API Key or a Client Session Token: those credentials are custodian-owned, retiring one is a no-op, and the listener is never fired for them — so keep using HttpUnauthorized as your signal to refresh a CST. It matters under Client Auth, where the credential is a session that is now spent.Carrying the bearer is the whole trigger — the host is not part of the test. A Portal API reached through your own apiHost override receives the token like any other, so its 401s retire the credential too, rather than leaving the SDK replaying a token the backend has already rejected.A 401 from a dApp gateway or a third-party RPC never triggers this, because the SDK sends those requests without a Portal credential in the first place: portal.request(...) attaches the bearer only to Portal’s own RPC hosts. However such a gateway answers, it cannot retire your credential.

Credentials (`PortalException.Credentials`)

Raised when a Portal instance cannot turn its credential into a bearer token. See Client Auth for how to recover from each reason.

Exception	Description
`PortalCredentialError`	A credential could not be resolved into a token. Exposes `reason` (a `PortalCredentialErrorReason`) and `requiresReauthentication`, which is `true` only for `SESSION_INVALIDATED`. Open, so a custom `PortalCredentials` implementation can specialize it without losing `reason`.
`InvalidApiKey`	A component was constructed with neither an `apiKey` nor `credentials`. Raised at construction, not on the first request. A blank or whitespace-only `apiKey` counts as absent.

PortalCredentialError.reason is one of:

Reason	Wire value	Description
`UNAVAILABLE`	`CREDENTIAL_UNAVAILABLE`	Resolution succeeded but produced nothing usable. Check that `Portal` was constructed with `apiKey` or `credentials`.
`PROVIDER_FAILURE`	`CREDENTIAL_PROVIDER_FAILURE`	The credential provider itself failed — a storage read, or a custom `PortalCredentials` implementation throwing. Retryable.
`SESSION_INVALIDATED`	`SESSION_INVALIDATED`	The session is known to be dead. Re-authenticate.

A token the MPC binary rejects does not surface as a PortalCredentialError. The binary makes its own HTTP calls, so the SDK reads its AUTH_FAILED result and throws PortalException.Mpc.MpcResultError as it always has — while still retiring the credential and firing onSessionInvalidated(). Existing catch blocks around createWallet, backupWallet, recoverWallet, and signing are unaffected.

Auth (`PortalException.Auth`)

Raised by PortalAuth during a Client Auth sign-in. Once a session exists, failures to turn it into a bearer token are Credentials errors instead.

Exception	Description
`MagicLinkNotConfigured`	`sendMagicLink()` was called with no `magicLink` config. Raised before any network call.
`AuthMethodUnavailable`	The provider is not enabled for this auth environment. Not retryable — read `getMethods()` and present the method as unavailable.
`AuthenticationFailed`	The redirect carried an `error` parameter: the provider sent the user back without a grant.
`MalformedResponse`	A response was missing its `{ "data": … }` envelope or a required field.
`InvalidGrantResponse`	The grant exchange returned neither a session token nor a `userJwt`.
`InvalidUserJwt`	The `userJwt` handed to `verifyTotp()` could not be read. Raised before the network call.
`SessionStorageFailure`	Device storage or the Keystore failed. Only retryable where nothing was consumed to get there — see Handle errors.

Transport failures are not remapped into PortalException.Auth. A grant the backend refuses — already used, expired, or issued for another environment — surfaces as PortalException.Api.HttpBadRequest carrying the backend’s message.

Connect (`PortalException.Connect`)

Exception	Description
`InvalidRequestMethod`	The WalletConnect request method is invalid.
`InvalidRequestParams`	The WalletConnect request parameters are invalid.

Provider (`PortalException.Provider`)

Exception	Description
`InvalidRequestParams`	The provider request parameters are invalid.
`NoAddress`	No address was found for the requested chain.
`NoRpcUrlFoundForChainId`	No RPC URL is configured for the given chain ID.
`NoSignatureFoundInSignResult`	The signing operation completed but returned no signature.
`UnsupportedRequestMethod`	The request method is not supported on this chain.
`NoBindingForSigningApprovalFound`	No signing approval callback is registered.
`UserDeclinedApproval`	The user declined the transaction approval prompt.
`InvalidIdempotencyKey`	The `idempotencyKey` in `RequestOptions` or `SendAssetParams` is empty after trimming, longer than 255 characters, or contains a character outside `A-Z a-z 0-9 . _ ~ -`. Raised before the approval prompt, so nothing is signed or sent. See Idempotency keys.
`IdempotencyKeyUnsupported`	An `idempotencyKey` was passed for `eth_sendRawTransaction`, `sol_sendTransaction`, or a Bitcoin `sendAsset`, whose broadcast Portal can’t protect. Raised before anything is sent.

Blockchain (`PortalException.Blockchain`)

Exception	Description
`InvalidChainId`	The chain ID string is malformed (missing `:` separator). Contains the invalid `chainId` value.
`NoSupportedCurveForChainId`	No supported cryptographic curve found for the given chain ID.
`NoSupportedNamespaceForChainId`	No supported namespace found for the given chain ID.

Migration from previous versions

In previous versions of the Android SDK, errors were thrown as generic Error, Exception, or flat PortalException subclasses like SendAssetArgumentError and PortalHttpUnauthorizedException. These legacy classes are now deprecated and will be removed in a future major version.

What changed

All generic Error(...) and Exception(...) throws have been replaced with specific PortalException subclasses.
Flat exception classes (SendAssetArgumentError, PortalHttpUnauthorizedException, PasskeyNotSupportedException, PasskeyStorageNotConfiguredException, MpcError, InvalidWalletStateError, StorageAuthError) now extend their corresponding PortalException subcategory. Your existing catch blocks will still work, but you should migrate to the new types.

Before and after

// Before — catching a flat legacy class
try {
    portal.backupWallet()
} catch (e: PortalHttpUnauthorizedException) {
    println("Unauthorized: ${e.message}")
} catch (e: Exception) {
    println("Something went wrong: ${e.message}")
}

// After — catching the structured exception
try {
    portal.backupWallet()
} catch (e: PortalException.Api.HttpUnauthorized) {
    println("Unauthorized: ${e.message}")
} catch (e: PortalException.Mpc) {
    println("MPC error: ${e.message}")
} catch (e: PortalException.Storage) {
    println("Storage error: ${e.message}")
}

Deprecated classes mapping

Deprecated class	Replace with
`SendAssetArgumentError`	`PortalException.Transaction.SendAssetArgumentError`
`PortalHttpUnauthorizedException`	`PortalException.Api.HttpUnauthorized`
`PasskeyNotSupportedException`	`PortalException.Storage.PasskeyNotSupported`
`PasskeyStorageNotConfiguredException`	`PortalException.Storage.PasskeyStorageNotConfigured`
`MpcError`	`PortalException.Mpc.MpcResultError`
`InvalidWalletStateError`	`PortalException.Wallet.InvalidWalletState`
`StorageAuthError`	`PortalException.Storage.StorageAuthError`

Getting Started

SDKs

APIs

Integrations

Resources

Error handling

Exception hierarchy

Catching exceptions

Catch a specific exception

Catch an entire category

Catch any Portal exception

Handle errors from `Result`-returning methods

Branch on the HTTP status code

Request timeouts

Absent shares versus unreadable shares

Exception reference

MPC (`PortalException.Mpc`)

Storage (`PortalException.Storage`)

Wallet (`PortalException.Wallet`)

Transaction (`PortalException.Transaction`)

API (`PortalException.Api`)

Credentials (`PortalException.Credentials`)

Auth (`PortalException.Auth`)

Connect (`PortalException.Connect`)

Provider (`PortalException.Provider`)

Blockchain (`PortalException.Blockchain`)

Migration from previous versions

What changed

Before and after

Deprecated classes mapping

​Exception hierarchy

​Catching exceptions

​Catch a specific exception

​Catch an entire category

​Catch any Portal exception

​Handle errors from Result-returning methods

​Branch on the HTTP status code

​Request timeouts

​Absent shares versus unreadable shares

​Exception reference

​MPC (PortalException.Mpc)

​Storage (PortalException.Storage)

​Wallet (PortalException.Wallet)

​Transaction (PortalException.Transaction)

​API (PortalException.Api)

​Credentials (PortalException.Credentials)

​Auth (PortalException.Auth)

​Connect (PortalException.Connect)

​Provider (PortalException.Provider)

​Blockchain (PortalException.Blockchain)

​Migration from previous versions

​What changed

​Before and after

​Deprecated classes mapping

Exception hierarchy

Catching exceptions

Catch a specific exception

Catch an entire category

Catch any Portal exception

Handle errors from `Result`-returning methods

Branch on the HTTP status code

Request timeouts

Absent shares versus unreadable shares

Exception reference

MPC (`PortalException.Mpc`)

Storage (`PortalException.Storage`)

Wallet (`PortalException.Wallet`)

Transaction (`PortalException.Transaction`)

API (`PortalException.Api`)

Credentials (`PortalException.Credentials`)

Auth (`PortalException.Auth`)

Connect (`PortalException.Connect`)

Provider (`PortalException.Provider`)

Blockchain (`PortalException.Blockchain`)

Migration from previous versions

What changed

Before and after

Deprecated classes mapping