Node.js SDK - Error Handling

The SDK distinguishes between two classes of failures:

Initial sync failures - surfaced as exceptions from NexusClient.create(). The application should refuse to start with an empty cache.
Background sync / SSE failures - never thrown. They are swallowed silently, 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-nodejs';

try {
  const value = client.getSecret('key');
} catch (err) {
  if (err instanceof NexusError) {
    // SDK-specific failure - handle as needed
  }
}

instanceof is the right test even when the package is loaded twice in one process, which happens whenever an application imports the SDK and a dependency requires it. The check is answered from a branded name chain rather than from object identity, so the ESM and CommonJS builds recognise each other’s errors - base and subclass alike. Subclassing an SDK error in your own code keeps ordinary semantics. A public key is refused whether it carries the wxp_ prefix or the backend reports it as public, so the guard does not depend on the prefix alone. The full hierarchy:

Error
└── NexusError                          (base class)
    ├── NexusConfigError                (NexusClient.create() - invalid config option)
    ├── NexusInitError                  (initial sync failure - cause has detail)
    ├── NexusUnauthorizedError          (HTTP 401)
    ├── NexusNotFoundError              (HTTP 404)
    ├── NexusPublicKeyError             (getSecret called with public key)
    ├── NexusSecretNotFoundError        (key absent from cache)
    ├── NexusBillingError               (v0.2.0) (HTTP 402 - tenant overdue)
    ├── NexusServiceKindMismatchError   (v0.2.0) (getSecret on a frontend-kind service)
    ├── NexusWIFNotConfiguredError      (v0.2.0) (no usable WIF provider matched)
    ├── NexusWIFTokenExchangeFailedError (v0.2.0) (token-exchange request failed)
    ├── NexusSessionExpiredError        (v0.2.0) (WIF session expired, refresh failed)
    ├── NexusRateLimitedError           (v0.5.0) (HTTP 429 on write endpoints)
    ├── NexusQuarantinedError           (v0.4.0) (HTTP 429 quarantine - sync path)
    ├── NexusAbAddonNotAvailableError   (v0.4.0) (HTTP 403 on evaluateAB)
    ├── NexusResponseTooLargeError      (response body exceeded the SDK's ceiling)
    ├── NexusTimeoutError               (connection or request exceeded its deadline)
    └── NexusClientClosedError          (a call made after client.close())

When each is thrown

Error	Thrown by	When
`NexusConfigError`	`NexusClient.create()`	A `NexusConfig` option is missing, malformed, or outside its accepted range. The message names the option and the offending value.
`NexusInitError`	`NexusClient.create()`	The initial sync failed for any reason. The `cause` property carries the underlying error (often `NexusUnauthorizedError` or a transport-level `Error`).
`NexusUnauthorizedError`	`create()`, `evaluateFlags`, `evaluateAB`, `setSecret`, `deleteSecret`, `deleteSecretVersion`	Server returned HTTP 401 - invalid API key, slug/key mismatch, or revoked key.
`NexusBillingError` (v0.2.0)	`create()`, background sync, `evaluateFlags`, `evaluateAB`, `setSecret`, `deleteSecret`, `deleteSecretVersion`	Server returned HTTP 402 - tenant has invoices overdue by more than 14 days. Background sync halts; the cache continues to serve. Check `client.billingOverdue`.
`NexusNotFoundError`	`create()`, `evaluateFlags`, `evaluateAB`, `deleteSecret`, `deleteSecretVersion`	Server returned HTTP 404 - unknown subdomain or missing endpoint (or, for the delete methods, an unknown key/version).
`NexusPublicKeyError`	`getSecret()`, `getSecretFilePath()`	The client uses a public key. Thrown synchronously, before the network call.
`NexusServiceKindMismatchError` (v0.2.0)	`getSecret()`, `getSecretFilePath()`	The service `kind` reported by the server is `"frontend"`. Frontend services must not hold secrets, regardless of key type.
`NexusSecretNotFoundError`	`getSecret()`	The requested key is not in the cache (or it’s a file-type secret - use `getSecretFilePath` for those). The `key` property carries the requested name.
`NexusWIFNotConfiguredError` (v0.2.0)	`create()`	`wif.enabled = true` but no usable workload-identity provider matched the running environment, or an explicit `tokenSource` returned an empty token. Wrapped in `NexusInitError` on the initial connect.
`NexusWIFTokenExchangeFailedError` (v0.2.0)	`create()`, background sync	`POST /v1/auth/token-exchange` returned a non-2xx response, or the body could not be decoded. Wrapped in `NexusInitError` on the initial connect.
`NexusSessionExpiredError` (v0.2.0)	background sync	The WIF session JWT has expired and the SDK could not refresh it. Cache continues to serve; refresh is retried on the next read.
`NexusRateLimitedError` (v0.5.0)	`setSecret`, `deleteSecret`, `deleteSecretVersion`, `evaluateFlags`, `evaluateAB`	Server returned HTTP 429 without a quarantine body - too many requests. Back off and retry.
`NexusQuarantinedError` (v0.4.0)	`_doSync` (sync path only), `refresh()`, `setSecret`, `deleteSecret`, `deleteSecretVersion`, `evaluateFlags`, `evaluateAB`	Server returned `429` with quarantine body (`{"error":"quarantined",...}`). `reason` and `expiresAt` are available as typed properties. Background sync is suppressed until `expiresAt` passes.
`NexusAbAddonNotAvailableError` (v0.4.0)	`evaluateAB`	Server returned HTTP 403 - the AB Testing add-on is not active for this project.
`NexusResponseTooLargeError`	`create()`, background sync	A response body exceeded the SDK’s ceiling (8 MiB). Reported as its own error rather than surfacing as a JSON-parse failure on a truncated document.
`NexusTimeoutError`	`create()`, background sync, the SSE stream	A connection or a request exceeded `connectTimeout` or `requestTimeout`.
`NexusClientClosedError`	any method after `client.close()`	The client has already released its timers, connections, and materialised secret files.

What is NOT thrown

Background syncs - silently retried on the next TTL tick. Cache served.
SSE transport errors - exponential backoff, 3-strike fallback to polling. No exception.
304 Not Modified - treated as success; TTL reset.
Missing config / flag - getConfig returns undefined; getFlag returns the defaultValue.
Unknown key in evaluateFlags - resolves to false per the server contract; never throws.

The asymmetry between secrets (throw) and configs/flags (sentinel) is deliberate: a missing secret usually means “you’re misconfigured, fail fast”, while a missing flag usually means “use the safe default and continue”.

Failure scenarios

Wrong API key

try {
  const client = await NexusClient.create({ endpoint, apiKey });
} catch (err) {
  if (err instanceof NexusInitError && err.cause instanceof NexusUnauthorizedError) {
    console.error('nexus: bad credentials - check NEXUS_API_KEY');
    process.exit(1);
  }
  throw err;
}

Slug doesn’t match key (Double-Gate failure)

In production, the backend validates that the slug embedded in endpoint matches the API key’s service. A mismatch returns 401 - same surface as above.

Network down at startup

If the Nexus backend is unreachable when create() runs, you get NexusInitError whose cause is a transport-level Error (ECONNREFUSED, ENOTFOUND, etc.).

async function createWithRetry(config: NexusConfig, retries = 5) {
  for (let i = 0; i < retries; i++) {
    try {
      return await NexusClient.create(config);
    } catch (err) {
      if (i === retries - 1) throw err;
      await new Promise((r) => setTimeout(r, 1000 * 2 ** i));
    }
  }
  throw new Error('unreachable');
}

Reading a secret with a public key

try {
  const value = client.getSecret('DB_PASSWORD');
} catch (err) {
  if (err instanceof NexusPublicKeyError) {
    console.error('nexus: public keys cannot read secrets - use a secret key');
  }
}

This check fires synchronously, before the network call.

Reading a secret that doesn’t exist

try {
  const value = client.getSecret('does.not.exist');
} catch (err) {
  if (err instanceof NexusSecretNotFoundError) {
    console.error(`missing secret: ${err.key}`);
  }
}

Reading a non-existent flag or config

Returns the default - no error:

client.getFlag('made.up.key', false);   // false
client.getConfig('made.up.key');        // undefined

SSE-specific behaviour

SSE failures never propagate to your code. The SDK silently logs them and falls back to polling after 3 strikes. To detect “live updates are no longer available”, check client.streamStatus:

if (client.streamStatus === 'fallback') {
  console.warn('nexus: SSE has fallen back to TTL polling');
}

Overview

Backend SDKs

Browser SDKs

OpenFeature Providers

Node.js SDK - Error Handling

Error hierarchy

When each is thrown

What is NOT thrown

Failure scenarios

Wrong API key

Slug doesn’t match key (Double-Gate failure)

Network down at startup

Reading a secret with a public key

Reading a secret that doesn’t exist

Reading a non-existent flag or config

SSE-specific behaviour

​Error hierarchy

​When each is thrown

​What is NOT thrown

​Failure scenarios

​Wrong API key

​Slug doesn’t match key (Double-Gate failure)

​Network down at startup

​Reading a secret with a public key

​Reading a secret that doesn’t exist

​Reading a non-existent flag or config

​SSE-specific behaviour

Error hierarchy

When each is thrown

What is NOT thrown

Failure scenarios

Wrong API key

Slug doesn’t match key (Double-Gate failure)

Network down at startup

Reading a secret with a public key

Reading a secret that doesn’t exist

Reading a non-existent flag or config

SSE-specific behaviour