React SDK - Error Handling

The SDK distinguishes between two classes of failures:

Initial sync failures - surfaced via NexusInitError from NexusProvider. Handle with an Error Boundary or the onError render prop.
Background sync / SSE failures - never thrown. They are logged via NexusLogger.error(...), and the existing cache continues to be served.

Error hierarchy

All SDK errors extend NexusError. A single instanceof check covers everything:

import { NexusError } from '@westyx-nexus/sdk-react';

if (err instanceof NexusError) {
  // SDK-specific failure - handle as needed
}

The full hierarchy:

Error
└── NexusError                          (base class)
    ├── NexusInitError                  (initial sync failure - cause has detail)
    ├── NexusUnauthorizedError          (HTTP 401)
    ├── NexusBillingError               (HTTP 402 - tenant has overdue invoices)
    ├── NexusAbAddonNotAvailableError   (HTTP 403 from evaluateAB - add-on disabled)
    ├── NexusServerError                (HTTP 5xx on /v1/sync, caught internally by the retry loop, v0.3.1)
    ├── NexusQuarantinedError           (HTTP 429 quarantine body - sync paused until expiresAt, v0.4.0)
    ├── NexusNotFoundError              (HTTP 404)
    ├── NexusPublicKeyError             (imperative getSecret with public key)
    ├── NexusServiceKindMismatchError   (imperative getSecret on kind=frontend service)
    └── NexusSecretNotFoundError        (imperative getSecret with unknown key)

When each is thrown

Error	Thrown by	When
`NexusInitError`	`NexusProvider` (during mount)	The initial sync failed for any reason. The `cause` property carries the underlying error.
`NexusUnauthorizedError`	Initial sync, manual `nexus.sync()`	Server returned HTTP 401 - invalid API key, slug/key mismatch, or revoked key.
`NexusBillingError` (v0.2.0)	Initial sync, background sync, `evaluateAB`	Server returned HTTP 402 - tenant has invoices overdue by more than 14 days. Background sync halts; the cache continues to serve. Use `useNexusBillingOverdue()` to detect the state.
`NexusAbAddonNotAvailableError` (v0.3.0)	`useEvaluateAB()` callback, `nexus.evaluateAB(...)`	Server returned HTTP 403 - the AB Testing add-on is not active for the tenant. Only `evaluate-ab` is gated; `useFlag` / `getFlag` keep working.
`NexusServerError` (v0.3.1)	`nexus.sync()` (caught internally)	Server returned HTTP 5xx on `/v1/sync`. The SDK catches this and schedules an exponential-backoff retry - consumers normally don’t see it. Exported for `instanceof` checks in custom hooks.
`NexusQuarantinedError` (v0.4.0)	`nexus.sync()`	Server returned HTTP 429 with `{"error":"quarantined"}` body. The `reason` (string) and `expiresAt` (Date) properties expose detail. The SDK automatically pauses background sync until `expiresAt`. The `onQuarantined` observer fires at the same time.
`NexusNotFoundError`	Initial sync, manual `nexus.sync()`, `evaluateAB`	Server returned HTTP 404 - unknown subdomain or missing endpoint.
`NexusPublicKeyError`	`useNexus().getSecret(...)`	The client uses a public key. Thrown synchronously by the imperative method. The hook `useSecret()` returns `undefined` instead.
`NexusServiceKindMismatchError` (v0.2.0)	`useNexus().getSecret(...)`	The service `kind` reported by the server is `"frontend"`. The hook `useSecret()` returns `undefined` instead.
`NexusSecretNotFoundError`	`useNexus().getSecret(...)`	The requested key is not in the cache. The hook `useSecret()` returns `undefined` instead.

Hooks vs imperative - non-throwing vs throwing

A subtle but deliberate API decision:

// Hooks - never throw, return undefined for missing/inaccessible
const stripe = useSecret('stripe.key');         // string | undefined
const banner = useConfig<string>('banner');     // string | undefined

// Imperative - throw on missing or inaccessible
const nexus = useNexus();
const stripe = nexus.getSecret('stripe.key');   // throws if missing or public key

Why? React component code reads from the cache on every render. If useSecret threw on a public key, every render would throw, breaking the component tree. The hook trades type safety (no string guarantee) for ergonomic component code.

Handling `NexusInitError`

Error Boundary (idiomatic React)

import { ErrorBoundary } from 'react-error-boundary';
import { NexusInitError, NexusProvider } from '@westyx-nexus/sdk-react';

function NexusErrorFallback({ error }: { error: Error }) {
  if (error instanceof NexusInitError) {
    return <h1>Configuration unavailable - try again later</h1>;
  }
  throw error;  // not for us - bubble up
}

<ErrorBoundary FallbackComponent={NexusErrorFallback}>
  <NexusProvider config={config}>
    <App />
  </NexusProvider>
</ErrorBoundary>

`onError` render prop

Inline handling without an Error Boundary:

<NexusProvider
  config={config}
  onError={(err) => {
    if (err instanceof NexusInitError && err.cause instanceof NexusUnauthorizedError) {
      return <h1>Bad credentials - check NEXUS_API_KEY</h1>;
    }
    return <h1>Service temporarily unavailable</h1>;
  }}
>
  <App />
</NexusProvider>

What is NOT thrown

Background syncs - silently retried on the next TTL tick. Cache served.
SSE transport errors - the SDK reconnects with exponential backoff, then falls back to TTL polling after 3 consecutive failures. No exception surfaces.
304 Not Modified - treated as success; TTL reset.
Hook reads for missing/inaccessible keys - return undefined (or the defaultValue for useFlag).

SSE-specific behaviour

SSE failures never propagate to your code. Use useNexusStreamStatus() to detect “live updates are no longer available”:

const { connected } = useNexusStreamStatus();

if (!connected) {
  return <Banner>Live updates paused - values may lag up to 60 s</Banner>;
}

5xx exponential backoff (v0.3.1+)

When the server returns a 5xx status on /sync, the SDK:

Catches the response internally and surfaces it as a NexusServerError(status, bodySnippet).
Increments an internal attempt counter and schedules a retry via setTimeout with exponential backoff:
Attempt Delay
1 1 s
2 2 s
3 4 s
4 8 s
5 16 s
6+ 30 s (capped)
Emits FALLBACK_REASON_TRANSPORT on the stream observer during the wait.
On the next successful sync - including the auto-retry succeeding - resets the counter.

Attempt	Delay
1	1 s
2	2 s
3	4 s
4	8 s
5	16 s
6+	30 s (capped)

import { NexusProvider, FALLBACK_REASON_TRANSPORT } from '@westyx-nexus/sdk-react';

<NexusProvider
  config={{
    baseUrl: '...',
    apiKey:  '...',
    streamObserver: {
      onFallback(reason) {
        if (reason === FALLBACK_REASON_TRANSPORT) {
          // 5xx wait - surface "syncing..." in the UI
        }
      },
    },
  }}
>
  <App />
</NexusProvider>

Overview

Backend SDKs

Browser SDKs

OpenFeature Providers

React SDK - Error Handling

Error hierarchy

When each is thrown

Hooks vs imperative - non-throwing vs throwing

Handling `NexusInitError`

Error Boundary (idiomatic React)

`onError` render prop

What is NOT thrown

SSE-specific behaviour

5xx exponential backoff (v0.3.1+)

​Error hierarchy

​When each is thrown

​Hooks vs imperative - non-throwing vs throwing

​Handling NexusInitError

​Error Boundary (idiomatic React)

​onError render prop

​What is NOT thrown

​SSE-specific behaviour

​5xx exponential backoff (v0.3.1+)

Error hierarchy

When each is thrown

Hooks vs imperative - non-throwing vs throwing

Handling `NexusInitError`

Error Boundary (idiomatic React)

`onError` render prop

What is NOT thrown

SSE-specific behaviour

5xx exponential backoff (v0.3.1+)