Errors

The SDK exposes specific error classes so you can catch and handle failure cases programmatically. All errors inherit from a base OxGasError.

OxGasError

The base class for all SDK errors. It includes a code property for easy matching.

import { OxGasError } from '0xgas-auth';

try {
  await client.login();
} catch (err) {
  if (err instanceof OxGasError) {
    console.log('Failed with code:', err.code);
  }
}

---

NotConnectedError

Thrown when calling a method that requires an active session (like getAddress(), setupSmartAccount(), or signMessage()) while the user is disconnected.

• Code: NOT_CONNECTED

Solution: Check client.isConnected() or call client.login() first.

---

SigningRejectedError

Thrown when the user clicks “Reject” or closes the widget during a signing request.

• Code: SIGNING_REJECTED

try {
  await client.signMessage(hash);
} catch (err) {
  if (err instanceof SigningRejectedError) {
    // Expected behavior: user decided not to sign. Show a toast or just ignore.
    toast('Transaction cancelled');
  }
}

---

SigningTimeoutError

Thrown when a request takes longer than its configured timeout.

• Code: SIGNING_TIMEOUT
• Extra properties: timeoutMs (the duration it waited before failing)

This can happen if the user leaves the tab open without responding to a sign request, or if they abandon the login flow midway.

Solution: You can increase loginTimeout or signTimeout in the constructor options if your users need more time.

---

WidgetError

Thrown when the widget iframe reports an internal error, authentication failure, or unexpected closure.

• Code: WIDGET_ERROR
• Extra properties: details? (raw error payload from the iframe)

This usually indicates a problem with the API key, network connectivity issues, or the user entering invalid credentials multiple times.

import { WidgetError } from '0xgas-auth';

try {
  await client.login();
} catch (err) {
  if (err instanceof WidgetError) {
    console.error('Widget failed:', err.message, err.details);
  }
}