Error Handling

Overview

Direct Auth and OAuth methods in @authrim/web return an AuthResponse<T> — a discriminated union that makes error handling type-safe and consistent:

type AuthResponse<T> =
  | { data: T; error: null }
  | { data: null; error: AuthError };

For these methods, check error first, then use data:

const { data, error } = await auth.passkey.login();

if (error) {
  // Handle error
  console.error(error.message);
  return;
}

// TypeScript knows data is non-null here
console.log(data.user);

Protected-resource helpers such as auth.stepUp, auth.customerProfiles, auth.devices, and auth.fetch() call HTTP APIs directly. Use try/catch around those methods when you need to handle request failures.

AuthError Structure

interface AuthError {
  /** Authrim error code (e.g., 'AR003002') */
  code: string;
  /** OAuth 2.0 error code (e.g., 'user_cancelled') */
  error: string;
  /** Human-readable error message */
  message: string;
  /** Whether the operation can be retried */
  retryable: boolean;
  /** Error severity level */
  severity: 'info' | 'warn' | 'error' | 'critical';
}

Error Code Format

Error codes follow the pattern AR{domain}{number}:

Prefix	Domain	Examples
AR001	Session / Auth	Session errors
AR002	Email Code	Send/verify errors
AR003	Passkey (WebAuthn)	Ceremony errors
AR004	Social Login	Provider/callback errors
AR005	OAuth / OIDC	Token/callback errors

Severity Levels

Level	Meaning	Typical Action
info	Expected state (e.g., not authenticated)	Update UI normally
warn	Recoverable issue (e.g., silent auth failed)	Log and continue
error	Failed operation (e.g., invalid code)	Show error message
critical	Unexpected failure (e.g., server error)	Show error + suggest retry

Retryable Flag

if (error.retryable) {
  showMessage('Something went wrong. Please try again.');
  // Offer retry button
} else {
  showMessage(error.message);
  // Don't offer retry — issue needs user action
}

Error Handling Patterns

Basic Pattern

const { data, error } = await auth.passkey.login();

if (error) {
  showErrorMessage(error.message);
  return;
}

// Success
redirect('/dashboard');

Switch on Error Code

const { data, error } = await auth.emailCode.verify(email, code);

if (error) {
  switch (error.code) {
    case 'AR002003':
      // Code expired — resend
      await auth.emailCode.send(email);
      showMessage('Code expired. A new code has been sent.');
      break;
    case 'AR002004':
      // Wrong code
      showMessage('Incorrect code. Please try again.');
      break;
    case 'AR002005':
      // Too many attempts
      showMessage('Too many attempts. Please wait before trying again.');
      break;
    default:
      showMessage(error.message);
  }
  return;
}

Severity-Based Handling

function handleAuthError(error: AuthError) {
  switch (error.severity) {
    case 'info':
      // Not really an error — expected state
      console.log(error.message);
      break;
    case 'warn':
      // Recoverable — log but don't alert
      console.warn(`[${error.code}] ${error.message}`);
      break;
    case 'error':
      // Show to user
      showToast(error.message, 'error');
      break;
    case 'critical':
      // Show prominently + log for debugging
      showAlert(error.message);
      logToService(error);
      break;
  }
}

Retry Pattern

async function loginWithRetry(maxRetries = 2) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const { data, error } = await auth.passkey.login();

    if (!error) {
      return data;
    }

    if (!error.retryable || attempt === maxRetries) {
      showMessage(error.message);
      return null;
    }

    // Brief delay before retry
    await new Promise(resolve => setTimeout(resolve, 1000));
  }

  return null;
}

Error Codes Reference

Passkey (AR003xxx)

Code	Error	Retryable	Description
AR003000	passkey_error	Varies	General passkey error
AR003001	webauthn_not_supported	No	Browser does not support WebAuthn
AR003002	user_cancelled	Yes	User cancelled the ceremony
AR003003	credential_not_found	No	No matching credential
AR003004	authenticator_error	Yes	Authenticator device error
AR003005	server_validation_failed	Yes	Server rejected the credential

Email Code (AR002xxx)

Code	Error	Retryable	Description
AR002000	email_code_error	Varies	General email code error
AR002001	invalid_email	No	Invalid email format
AR002002	rate_limited	No	Too many send requests
AR002003	code_expired	No	Verification code expired
AR002004	invalid_code	Yes	Wrong code entered
AR002005	max_attempts	No	Too many failed verifications

Social Login (AR004xxx)

Code	Error	Retryable	Description
AR004001	provider_not_configured	No	Provider not set up
AR004002	popup_blocked	No	Browser blocked the popup
AR004003	user_denied	Yes	User denied consent
AR004004	provider_error	Yes	Provider returned an error
AR004005	callback_failed	No	Callback validation failed

OAuth (AR005xxx)

Code	Error	Retryable	Description
AR005001	oauth_callback_error	No	Callback handling failed
AR005002	silent_auth_failed	No	Silent authentication failed
AR005003	no_tokens	No	No tokens received
AR005004	popup_login_error	Yes	Popup login failed

Centralized Error Handler

Create a reusable error handler for your application:

function handleError(error: AuthError, context: string) {
  // Log all errors
  console.error(`[${context}] ${error.code}: ${error.message}`);

  // User-facing message
  if (error.severity === 'critical') {
    showAlert('An unexpected error occurred. Please try again later.');
  } else if (error.severity === 'error') {
    showToast(error.message);
  }

  // Analytics
  trackError({ code: error.code, context, severity: error.severity });
}

// Usage
const { data, error } = await auth.passkey.login();
if (error) {
  handleError(error, 'passkey-login');
  return;
}

Next Steps

• Events — Listen for auth state changes
• Configuration Reference — All SDK options
• Session Management — Session operations