Error Handling

The Openfort SDK provides a comprehensive error handling system with typed error classes and error codes to help you handle specific failure scenarios gracefully.

Error Classes

All Openfort errors extend the base OpenfortError class. Import the error classes you need:

import {
  OpenfortError,
  AuthenticationError,
  AuthorizationError,
  ConfigurationError,
  OAuthError,
  OTPError,
  RecoveryError,
  RequestError,
  SessionError,
  SignerError,
  UserError,
} from '@openfort/openfort-js'

OpenfortError

The base error class that all other Openfort errors extend. Contains common properties:

class OpenfortError extends Error {
  code: string       // Error code for programmatic handling
  message: string    // Human-readable error message
}

AuthenticationError

Thrown when authentication fails (invalid credentials, expired tokens, etc.).

try {
  await openfort.auth.logInWithEmailPassword({ email, password })
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.log('Authentication failed:', error.message)
    // Show login error to user
  }
}

AuthorizationError

Thrown when the user lacks permission to perform an action.

try {
  await openfort.embeddedWallet.exportPrivateKey()
} catch (error) {
  if (error instanceof AuthorizationError) {
    console.log('Not authorized:', error.message)
    // Prompt user to authenticate or request access
  }
}

ConfigurationError

Thrown when the SDK is misconfigured (missing keys, invalid options).

try {
  const openfort = new Openfort({
    baseConfiguration: { publishableKey: '' }, // Missing key!
  })
} catch (error) {
  if (error instanceof ConfigurationError) {
    console.log('Configuration error:', error.message)
    // Check SDK configuration
  }
}

OAuthError

Thrown when OAuth authentication fails.

try {
  await openfort.auth.storeCredentials({ token, userId })
} catch (error) {
  if (error instanceof OAuthError) {
    console.log('OAuth error:', error.message)
    // Handle OAuth-specific error
  }
}

OTPError

Thrown when OTP (one-time password) operations fail.

try {
  await openfort.auth.logInWithEmailOtp({ email, otp })
} catch (error) {
  if (error instanceof OTPError) {
    console.log('OTP error:', error.message)
    // Show OTP-specific error (expired, invalid, etc.)
  }
}

RecoveryError

Thrown when wallet recovery operations fail.

try {
  await openfort.embeddedWallet.recover({
    account: accountId,
    recoveryParams: { recoveryMethod: 'password', password: '...' },
  })
} catch (error) {
  if (error instanceof RecoveryError) {
    console.log('Recovery failed:', error.message)
    // Handle recovery-specific error
  }
}

RequestError

Thrown when API requests fail (network errors, server errors).

try {
  await openfort.embeddedWallet.list()
} catch (error) {
  if (error instanceof RequestError) {
    console.log('Request failed:', error.message)
    // Handle network or server error
  }
}

SessionError

Thrown when session operations fail (not logged in, session expired).

try {
  await openfort.user.get()
} catch (error) {
  if (error instanceof SessionError) {
    console.log('Session error:', error.message)
    // Redirect to login
  }
}

SignerError

Thrown when signer operations fail (signing, wallet not configured).

try {
  await openfort.embeddedWallet.signMessage('Hello')
} catch (error) {
  if (error instanceof SignerError) {
    console.log('Signer error:', error.message)
    // Configure wallet first
  }
}

UserError

Thrown when user operations fail (user not found, invalid user data).

try {
  await openfort.auth.addEmail({ email, callbackURL })
} catch (error) {
  if (error instanceof UserError) {
    console.log('User error:', error.message)
    // Handle user-specific error
  }
}

Error Codes

The SDK exports error code constants for programmatic error handling:

import {
  OPENFORT_ERROR_CODES,
  OPENFORT_AUTH_ERROR_CODES,
} from '@openfort/openfort-js'

Authentication Error Codes

const OPENFORT_AUTH_ERROR_CODES = {
  ALREADY_LOGGED_IN: 'already_logged_in',
  NOT_LOGGED_IN: 'not_logged_in',
  INVALID_CREDENTIALS: 'invalid_credentials',
  INVALID_TOKEN: 'invalid_token',
  TOKEN_EXPIRED: 'token_expired',
  EMAIL_NOT_VERIFIED: 'email_not_verified',
  MISSING_SIGNER: 'missing_signer',
  // ... and more
}

Best Practices

1. Use `instanceof` for Type Checking

Always use instanceof to check error types:

try {
  await someOpenfortOperation()
} catch (error) {
  if (error instanceof AuthenticationError) {
    // Handle authentication error
  } else if (error instanceof ConfigurationError) {
    // Handle configuration error
  } else if (error instanceof OpenfortError) {
    // Handle any other Openfort error
  } else {
    // Handle unexpected errors
    throw error
  }
}

2. Handle Errors Gracefully

Provide user-friendly messages:

const getErrorMessage = (error: unknown): string => {
  if (error instanceof AuthenticationError) {
    return 'Invalid email or password. Please try again.'
  }
  if (error instanceof SessionError) {
    return 'Your session has expired. Please log in again.'
  }
  if (error instanceof OTPError) {
    return 'Invalid or expired code. Please request a new one.'
  }
  if (error instanceof OpenfortError) {
    return 'An error occurred. Please try again.'
  }
  return 'An unexpected error occurred.'
}