Errors

The SDK throws plain Error instances with a well-known name. Pattern-match on name to branch your UI; the human-readable message is for logs.

error.name	When	What to do
SigilConfigError	Missing organizationId, publishableKey, iframeUrl; or authMode: 'oidc' without getToken.	Fix your provider config; this is a 100% reproducible bug.
SigilOriginError	The current window.location.origin is not in the org’s allowed origins.	Add the origin in the portal Settings page.
SigilAuthError	Bad publishable key, expired/invalid JWT, OTP wrong, etc.	Surface a generic “couldn’t sign you in” message, log the cause.
SigilRejectedError	The user clicked Reject in the confirmation modal.	Treat as a clean abort. Do not retry automatically.
SigilTimeoutError	Iframe didn’t reply within 30s. Usually means the user closed the tab or lost their connection.	Offer a retry.
SigilNetworkError	The iframe couldn’t reach api.sigilkeys.com.	Show a “you appear to be offline” banner.
SigilRecoveryRequired	The user has a wallet on another device; Device share missing here.	Hand off — the iframe will show the recovery UI on its own. You may want to inform the user that they’re about to recover.

React

In React the same errors land in useWallet().error (for init-phase failures) or in the rejected promise from useSignMessage().signMessage (for sign-phase failures).

const { signMessage } = useSignMessage();

try {
  await signMessage('hi');
} catch (e) {
  if (e instanceof Error && e.name === 'SigilRejectedError') return; // user said no
  if (e instanceof Error && e.name === 'SigilTimeoutError') {
    showToast('Wallet didn\'t respond. Try again.');
    return;
  }
  reportError(e);
}

Sentry / observability

The SDK does not ship with any telemetry. Wrap the methods at the call site with whatever observability stack you use.