Angular SDK - Error Handling

The SDK distinguishes between two classes of failures:

Initial sync failures - surfaced as exceptions during APP_INITIALIZER. The Angular bootstrap fails, which is the correct behaviour for a configuration source.
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-angular';

try {
  const banner = nexus.getConfig('public.banner');
} catch (err) {
  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 - overdue invoices, v0.2.0)
    ├── NexusServiceKindMismatchError   (getSecret on kind=frontend, v0.2.0)
    ├── NexusAbAddonNotAvailableError   (evaluateAB on tenant without AB add-on, v0.3.0)
    ├── NexusServerError                (HTTP 5xx on /sync, caught internally by the retry loop, v0.3.1)
    ├── NexusQuarantinedError           (HTTP 429 quarantined - reason + expiresAt, v0.4.0)
    ├── NexusNotFoundError              (HTTP 404)
    ├── NexusPublicKeyError             (getSecret called with public key)
    └── NexusSecretNotFoundError        (key absent from cache)

When each is thrown

Error	Thrown by	When
`NexusInitError`	`provideNexus()` / `NexusModule.forRoot()` (during bootstrap)	The initial sync failed for any reason. The `cause` property carries the underlying error.
`NexusUnauthorizedError`	Initial sync, `nexus.sync()`	Server returned HTTP 401 - invalid API key, slug/key mismatch, or revoked key.
`NexusBillingError`	Initial sync, `nexus.sync()`	Server returned HTTP 402 - the tenant has overdue invoices. The SDK halts the background refresh loop. Cleared on the next successful sync.
`NexusServiceKindMismatchError`	`getSecret()`	The service’s `kind` is `"frontend"`. Frontend services are public by design and must not hold secrets.
`NexusAbAddonNotAvailableError`	`evaluateAB()`, `evaluateABPromise()`	Server returned HTTP 403 - the AB Testing add-on is not active for the tenant.
`NexusServerError`	`nexus.sync()` (caught internally, v0.3.1)	Server returned HTTP 5xx on `/sync`. The SDK catches this and schedules an exponential-backoff retry. Exported for `instanceof` checks in custom logging interceptors.
`NexusQuarantinedError`	`nexus.sync()` (v0.4.0)	Server returned HTTP 429 with `{"error":"quarantined"}`. Carries `reason: string` and `expiresAt: Date`. The SDK suspends sync until `expiresAt` and fires `onQuarantined` on the stream observer.
`NexusNotFoundError`	Initial sync, `nexus.sync()`, `evaluateAB()`	Server returned HTTP 404 - unknown subdomain or missing endpoint.
`NexusPublicKeyError`	`nexus.getSecret()`	The client uses a public key. Thrown synchronously. Browser SDKs always throw this for `getSecret`.
`NexusSecretNotFoundError`	`nexus.getSecret()`	Practically never reached in browsers, since `NexusPublicKeyError` fires first.

Catching during an `APP_INITIALIZER` failure

The default behaviour is to fail the bootstrap. To recover gracefully (e.g. show a degraded UI), you can wrap the bootstrap:

// main.ts
import { bootstrapApplication } from '@angular/platform-browser';
import { NexusInitError } from '@westyx-nexus/sdk-angular';
import { AppComponent } from './app/app.component';
import { appConfig } from './app/app.config';

bootstrapApplication(AppComponent, appConfig).catch((err) => {
  if (err instanceof NexusInitError) {
    document.body.innerHTML = '<h1>Service temporarily unavailable</h1>';
  } else {
    throw err;
  }
});

Quarantine handling (v0.4.0+)

When the Nexus backend places a service in quarantine it responds HTTP 429 with a JSON body containing "error":"quarantined", a "reason" string, and an ISO-8601 "expires_at" timestamp. The SDK:

Throws NexusQuarantinedError (carrying reason and expiresAt) from sync().
Fires onQuarantined(reason, expiresAt) on the stream observer (if set).
Suspends ensureFresh background syncing until expiresAt.
On the stream pre-flight, schedules a reconnect after the quarantine window (minimum 5 s) without incrementing the failure counter.

import { NexusQuarantinedError } from '@westyx-nexus/sdk-angular';

try {
  await nexus.sync();
} catch (err) {
  if (err instanceof NexusQuarantinedError) {
    console.warn(`Quarantined: ${err.reason} until ${err.expiresAt.toISOString()}`);
  }
}

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 { provideNexus, FALLBACK_REASON_TRANSPORT } from '@westyx-nexus/sdk-angular';

provideNexus({
  baseUrl: '...',
  apiKey: '...',
  streamObserver: {
    onFallback(reason) {
      if (reason === FALLBACK_REASON_TRANSPORT) {
        // 5xx wait - surface "syncing..." in the UI
      }
    },
  },
});

Overview

Backend SDKs

Browser SDKs

OpenFeature Providers

Angular SDK - Error Handling

Error hierarchy

When each is thrown

Catching during an `APP_INITIALIZER` failure

Quarantine handling (v0.4.0+)

5xx exponential backoff (v0.3.1+)

​Error hierarchy

​When each is thrown

​Catching during an APP_INITIALIZER failure

​Quarantine handling (v0.4.0+)

​5xx exponential backoff (v0.3.1+)

Error hierarchy

When each is thrown

Catching during an `APP_INITIALIZER` failure

Quarantine handling (v0.4.0+)

5xx exponential backoff (v0.3.1+)