APIError for general SDK errors, and WithdrawError for withdrawal-specific failures. Type guard functions are exported for programmatic error handling.
Import
import {
APIError,
VaultNotFoundByAddressError,
VaultNotFoundByNameError,
UnauthorizedVaultAccessError,
isVaultNotFoundByAddressError,
isVaultNotFoundByNameError,
} from '@paxoslabs/amplify-sdk'
APIError Class
class APIError extends Error {
/** Human-readable error description */
message: string
/** HTTP status code (if applicable) */
statusCode?: number
/** SDK function that threw the error (e.g., "prepareDepositAuthorization") */
endpoint?: string
/** Original error cause */
cause?: unknown
}
WithdrawError Hierarchy
Withdrawal operations throw specialized error subclasses with acode property for programmatic handling.
class WithdrawError extends Error {
code: string
context?: Record<string, unknown>
}
Exported Error Classes
| Class | Code | When Thrown |
|---|---|---|
VaultNotFoundByAddressError | VAULT_NOT_FOUND_BY_ADDRESS | Account address doesn’t match any known account |
VaultNotFoundByNameError | VAULT_NOT_FOUND_BY_NAME | Account name doesn’t match any known account |
UnauthorizedVaultAccessError | UNAUTHORIZED_VAULT_ACCESS | API key lacks access to the requested account |
Internal Error Subclasses
These are thrown internally but can be caught asWithdrawError:
| Code | Description |
|---|---|
VAULT_NOT_FOUND | General account lookup failure |
MULTIPLE_VAULTS_FOUND | Ambiguous account filter matched multiple accounts |
INVALID_ADDRESS | Malformed address parameter |
INVALID_SHARE_AMOUNT | Share amount is zero or negative |
INVALID_SLIPPAGE | Slippage outside valid range |
INVALID_YIELD_TYPE | Unrecognized yield type value |
INVALID_CHAIN_ID | Unsupported chain ID |
TRANSACTION_DATA_ERROR | Failed to encode transaction data |
VAULT_CACHE_EMPTY | Account cache not populated yet |
Error Type Guards
import {
isVaultNotFoundByAddressError,
isVaultNotFoundByNameError,
} from '@paxoslabs/amplify-sdk'
try {
const txData = await prepareWithdrawOrderTxData(params)
} catch (error) {
if (isVaultNotFoundByNameError(error)) {
console.log(error.code) // "VAULT_NOT_FOUND_BY_NAME"
console.log(error.context) // { vaultName: "..." }
}
if (isVaultNotFoundByAddressError(error)) {
console.log(error.code) // "VAULT_NOT_FOUND_BY_ADDRESS"
console.log(error.context) // { vaultAddress: "0x..." }
}
}
Usage
import { APIError, prepareDepositAuthorization } from '@paxoslabs/amplify-sdk'
try {
const auth = await prepareDepositAuthorization(params)
} catch (error) {
if (error instanceof APIError) {
console.log(error.message) // "No vault found for token 0x... with yield type 'CORE' on chain 1"
console.log(error.endpoint) // "prepareDepositAuthorization"
console.log(error.statusCode) // 404 (if from an HTTP response)
}
}
Common Error Scenarios
Initialization
| Error Message Pattern | Description | Resolution |
|---|---|---|
"API key cannot be empty" | Empty or missing API key | Provide a valid pxl_... key |
"Invalid API key format" | Key doesn’t meet minimum length | Check key format |
"SDK not initialized" | SDK function called before initAmplifySDK() | Call initAmplifySDK() at app startup |
Deposits
| Error Message Pattern | Description | Resolution |
|---|---|---|
"No vault found for token..." | No account matches yieldType, token, and chainId | Verify parameters with getSupportedAssets() |
"Token does not support EIP-2612 permit" | Token lacks permit support | Use approval flow or forceMethod: "approval" |
"Invalid slippage value" | Slippage outside 0–10000 bps | Provide value between 0 and 10000 |
Withdrawals
| Error Message Pattern | Description | Resolution |
|---|---|---|
"No vault found for asset..." | No account matches parameters | Verify yieldType, wantAsset, and chainId |
"WithdrawQueue contract address not configured" | Account missing queue address | Contact support — account may not support withdrawals yet |
"Failed to check withdrawal approval" | On-chain multicall failed | Check RPC connectivity and retry |
Error Handling Patterns
Basic Error Handling
try {
const auth = await prepareDepositAuthorization(params)
} catch (error) {
if (error instanceof APIError) {
if (error.message.includes('No vault found')) {
showError('This token is not supported for the selected yield type')
} else if (error.message.includes('not initialized')) {
await initAmplifySDK(apiKey)
} else {
showError(error.message)
}
}
}
Logging Errors
try {
const prepared = await prepareDeposit(params)
} catch (error) {
if (error instanceof APIError) {
console.error({
endpoint: error.endpoint,
statusCode: error.statusCode,
message: error.message,
})
errorTracker.capture(error, {
extra: {
endpoint: error.endpoint,
statusCode: error.statusCode,
},
})
}
}
User-Friendly Messages
function getUserMessage(error: APIError): string {
if (error.message.includes('not initialized')) {
return 'Please wait while we connect...'
}
if (error.message.includes('No vault found')) {
return 'This token is not available for the selected strategy.'
}
if (error.message.includes('not support EIP-2612')) {
return 'Please approve the transaction in your wallet.'
}
return 'An unexpected error occurred. Please try again.'
}
Related
- Troubleshooting - Common issues and solutions
- Logging Guide - Debug logging configuration