Error handling

In-depth error handling: error types, retry strategies, user messaging, and recovery patterns for the Humanity React SDK.

The SDK provides typed error classes and utilities so you can handle failures precisely — whether it's an expired token, a blocked popup, or a failed verification.

Error Types

All SDK errors are instances of HumanityReactError, which carries:

• message — human-readable description

• code — machine-readable error code (e.g. 'invalid_grant', 'token_expired', 'popup_blocked')

• status — HTTP status code when applicable

import { isHumanityError, type HumanityReactError } from '@humanity-org/react-sdk';

function handleError(err: unknown) {
  if (isHumanityError(err)) {
    console.error('Humanity error:', {
      message: err.message,
      code: err.code,
      status: err.status,
    });
  }
}

Global Error Handler

Use the onError prop on HumanityProvider to catch all auth and verification errors in one place — ideal for routing to an error reporting service:

import { HumanityProvider } from '@humanity-org/react-sdk';
import * as Sentry from '@sentry/react';

<HumanityProvider
  clientId="hp_xxx"
  redirectUri="https://app.com/callback"
  onError={(error) => {
    Sentry.captureException(error, {
      extra: { code: error.code, status: error.status },
    });
  }}
>
  <App />
</HumanityProvider>

Per-Component Error Callbacks

Each component that performs async operations (HumanityConnect, HumanityVerify) accepts an onError prop for local handling:

<HumanityConnect
  scopes={['openid', 'profile']}
  onSuccess={(result) => handleLogin(result)}
  onError={(error) => {
    if (error.code === 'popup_blocked') {
      showToast('Please allow popups for this site.');
    } else {
      showToast('Login failed. Please try again.');
    }
  }}
/>

Error Boundary

Wrap authentication-critical UI with HumanityErrorBoundary to catch unexpected render-time errors:

import { HumanityErrorBoundary, HumanityConnect } from '@humanity-org/react-sdk';

<HumanityErrorBoundary
  fallback={(error) => (
    <div>
      <p>Authentication unavailable: {error.message}</p>
      <button onClick={() => window.location.reload()}>Retry</button>
    </div>
  )}
  onError={(error, info) => {
    console.error('Boundary caught:', error, info.componentStack);
  }}
>
  <HumanityConnect />
</HumanityErrorBoundary>

Hook-Level Error State

Hooks expose an error field you can check directly:

import { useAuth, useVerification } from '@humanity-org/react-sdk';

function AuthStatus() {
  const { error: authError } = useAuth();
  const { status, error: verifyError } = useVerification();

  if (authError) return <p>Auth error: {authError.message}</p>;
  if (status === 'error') return <p>Verification error: {verifyError?.message}</p>;

  return null;
}

Error Utilities

Export	Description
isHumanityError	Type guard — returns true if the value is a HumanityReactError.
createError	Factory for creating typed SDK errors.
normalizeError	Converts any thrown value into a HumanityReactError.
parseOAuthError	Parses OAuth error parameters from a callback URL.

Common Error Codes

Code	Cause	Fix
popup_blocked	Browser blocked the OAuth popup	Prompt user to allow popups, or use mode="redirect"
token_expired	Access token has expired	Call refreshToken() or prompt re-login
invalid_grant	Refresh token is invalid or revoked	Prompt re-login
access_denied	User declined the OAuth consent screen	Show an informative message and retry option
network_error	Request failed due to connectivity	Retry after checking network
scope_mismatch	Requested scopes don't match registered application	Verify scopes in the Developer Portal

Production Checklist

Before going live, verify:

• onError global handler is configured and routes to your monitoring service

• HumanityErrorBoundary wraps authentication-critical UI

• popup_blocked case is handled (show instructions or fall back to redirect mode)

• Token expiry is handled gracefully (auto-refresh or re-login prompt)

• Redirect URI is registered for both sandbox and production environments

• storage="memory" is used, or you've explicitly accepted the XSS risk of localStorage