Skip to main content

Error Pattern

All SDK methods return AttestSDKResponse<T> to provide consistent error handling:
type AttestSDKResponse<T = undefined> =
  | { data: T; error?: undefined }
  | { data?: undefined; error: any }

Basic Usage

const result = await sdk.fetchAuthority();
if (result.error) {
  // Handle error
  return;
}
// Use result.data

Stellar Errors

Network Errors

ErrorCodeDescriptionSolution
Connection FailedN/ARPC endpoint unreachableCheck internet connection, verify endpoint URL
Account Not Found404Stellar account doesn’t existFund account with XLM or check public key
Insufficient BalanceN/ANot enough XLM for transactionAdd XLM to account

Transaction Errors

ErrorCodeDescriptionSolution
Transaction Failedtx_failedTransaction execution failedCheck transaction parameters and account state
Invalid Schema UIDN/ASchema UID format incorrectUse 64-character hex string (transaction hash)
Operation Failedop_*Specific operation failedCheck operation-specific requirements

Contract Errors

ErrorCodeDescriptionSolution
Contract Not FoundN/ASoroban contract not deployedVerify contract address
UnauthorizedN/ANot authorized for operationRegister as authority first
Execution FailedN/AContract execution errorCheck contract state and parameters

Solana Errors

Program Errors

ErrorCodeDescriptionSolution
InvalidSchema6000Schema format invalidFix schema content format
NotFound6001Attestation not foundVerify attestation UID exists
AlreadyRevoked6002Attestation already revokedCheck revocation status first
Irrevocable6003Schema doesn’t allow revocationUse revocable schema
InvalidExpirationTime6004Invalid expiration timestampUse future timestamp
DataTooLarge6005Attestation data too largeReduce data size
WrongAsset6006Incorrect token for levyUse correct token mint
Unauthorized6009Not authorizedRegister as authority
SchemaAlreadyExists6010Schema name takenUse different schema name

Network Errors

ErrorCodeDescriptionSolution
Insufficient Funds-32002Not enough SOLAdd SOL to wallet
Blockhash Not FoundN/ATransaction expiredRetry with fresh blockhash
Account Not Found-32602Account doesn’t existCreate account first
Simulation FailedN/ATransaction simulation failedCheck transaction validity

Token Errors

ErrorCodeDescriptionSolution
Missing Token AccountN/AAssociated token account missingCreate token account
Insufficient TokensN/ANot enough tokens for levyAdd tokens to wallet
Invalid MintN/AToken mint not recognizedUse correct mint address

Error Handling Patterns

Basic Error Check

const result = await sdk.someOperation();
if (result.error) {
  console.error('Operation failed:', result.error);
  return null;
}
return result.data;

Chain-Specific Handling

function handleError(error: any, chain: 'stellar' | 'solana'): string {
  if (chain === 'stellar') {
    if (error.status === 404) return 'Account not found';
    if (error.message?.includes('insufficient')) return 'Insufficient XLM';
  }
  
  if (chain === 'solana') {
    if (error.code === 6010) return 'Schema already exists';
    if (error.code === 6001) return 'Attestation not found';
  }
  
  return error.message || 'Unknown error';
}

Retry Logic

async function withRetry<T>(
  operation: () => Promise<AttestSDKResponse<T>>,
  maxRetries: number = 3
): Promise<AttestSDKResponse<T>> {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    const result = await operation();
    if (!result.error) return result;
    
    const errorStr = result.error.toString().toLowerCase();
    if (errorStr.includes('unauthorized') || errorStr.includes('invalid')) {
      break; // Don't retry these
    }
    
    if (attempt < maxRetries) {
      await new Promise(resolve => setTimeout(resolve, 1000 * attempt));
    }
  }
  
  return { error: 'Max retries exceeded' };
}

Common Solutions

Insufficient Balance

  • Stellar: Add XLM to account (minimum ~2.5 XLM for reserves)
  • Solana: Add SOL to wallet (transaction fees + account rent)

Account/Attestation Not Found

  • Verify addresses and UIDs are correct
  • Check if account is funded (Stellar) or created (Solana)
  • Confirm attestation exists on correct network

Authorization Errors

  • Register wallet as authority using registerAuthority()
  • Verify correct wallet is being used for operations
  • Check authority permissions for specific operations

Network Issues

  • Verify internet connection
  • Check RPC endpoint status
  • Try different RPC endpoint if available
  • Implement retry logic for temporary failures

Schema/Data Format Errors

  • Validate schema content format: field:type,field:type
  • Ensure attestation data matches schema structure
  • Check data size limits (varies by chain)
  • Use proper data types for each field