React SDK - Error handling

Every error the SDK raises extends NexusError, carries a stable name, and survives instanceof after transpilation.

The hierarchy

Error	Raised when
`NexusConfigError`	An option is missing, mistyped or out of range. Carries `option`, `reason` and the value.
`NexusInitError`	The initial sync could not complete. The underlying failure is on `cause`.
`NexusUnauthorizedError`	HTTP 401 - the key is invalid, or does not match this host.
`NexusBillingError`	HTTP 402 - the tenant has overdue invoices.
`NexusNotFoundError`	HTTP 404 - the service or endpoint does not exist.
`NexusQuarantinedError`	HTTP 429 with a quarantine body. Carries `reason` and `expiresAt`.
`NexusServerError`	HTTP 5xx, or a 429 without a quarantine. Carries `status`, `bodySnippet`, `retryAfterMs`.
`NexusTimeoutError`	A request exceeded its deadline. Carries `operation` and `timeoutMs`.
`NexusResponseTooLargeError`	A response body exceeded 8 MiB.
`NexusAbAddonNotAvailableError`	HTTP 403 from AB evaluation - the add-on is not active.
`NexusClosedError`	A method was called on a client that has been closed.

Which of these you will actually see

Most of them are handled inside the SDK and never surface. At startup - NexusConfigError for a mistake in the options, or NexusInitError if the first sync fails. Both are worth surfacing to the developer; neither is a runtime condition to design around. From AB evaluation - NexusAbAddonNotAvailableError when the add-on is not active. Fall back to the cached flag. Everything else is absorbed. A 5xx is retried, a 429 is waited out, a 402 slows the refresh loop, a timeout is retried. Throughout, reads keep returning the last good snapshot, so there is nothing for the application to do.

try {
  const results = await evaluateAB(['checkout.v2'], user.id, { plan: user.plan });
  setNewCheckout(results['checkout.v2'] === true);
} catch (err) {
  if (err instanceof NexusAbAddonNotAvailableError) {
    setNewCheckout(false);          // the add-on is off; use the plain flag
  } else {
    setNewCheckout(false);          // anything else: fail closed
  }
}

Billing

A 402 does not stop the client. Reads keep being served from the snapshot, and the refresh loop slows to one attempt every five minutes rather than halting - so the client recovers on its own once the invoice is settled, with nothing to restart. Surface it passively if you want to:

const { connected, state } = useNexusStreamStatus();
const overdue = useNexusBillingOverdue();

Public keys and secrets

A browser client holds a public key, so it has no getSecret() method at all (removed in v0.16.0 - it could only ever throw). Secrets belong in a backend SDK; there is no configuration that makes them reachable from a browser.

Errors do not leak key material

A configuration rejection naming the API key carries only its prefix. A server error carries at most a 256-character body snippet. No error message contains a secret’s value or a secret’s key name.

Overview

Backend SDKs

Browser SDKs

OpenFeature Providers

React SDK - Error handling

The hierarchy

Which of these you will actually see

Billing

Public keys and secrets

Errors do not leak key material

​The hierarchy

​Which of these you will actually see

​Billing

​Public keys and secrets

​Errors do not leak key material

The hierarchy

Which of these you will actually see

Billing

Public keys and secrets

Errors do not leak key material