Skip to main content
The SDK distinguishes between two classes of failures:
  1. Initial sync failures - surfaced as exceptions. The application context refuses to start with an empty cache.
  2. Background sync / SSE failures - never thrown. They are logged at Error level through the SDK’s ILogger, and the existing cache continues to be served.

Exception hierarchy

All SDK exceptions extend NexusException. A single catch clause covers everything:
The full hierarchy:

When each is thrown

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 surfaces.
  • A switched-off environment on the stream - no transport error is counted; the stream falls back to polling at once (OnFallback("environment-disabled")) and reconnects on the SseReconnectCooldown schedule.
  • A locked-down service on the stream (423 service_locked) - the stream exits immediately (OnFallback(FallbackReason.ServiceLocked)) and background sync retries halt until an explicit SyncAsync() succeeds; call ConnectStream() afterwards to restart the stream.
  • 304 Not Modified - treated as success; TTL reset.
  • Missing config / flag - GetConfig returns (null, false); GetFlag returns the defaultValue.
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

Reading a secret with a public key

Reading a secret that doesn’t exist

SSE-specific behaviour

SSE failures never propagate to your code. The SDK logs each transport error at Error level under the Westyx.Nexus.Stream category, keeps serving the cache, and reconnects:
To react when live updates stop and resume, implement an IStreamObserver: OnDisconnected, OnFallback and OnConnected report each transition as it happens.