- 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 logged through the logger, and the existing cache continues to be served.
Error hierarchy
All SDK errors extendNexusError. A single instanceof check covers everything:
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:
When each is thrown
What is NOT thrown
- Background syncs - a failure is logged at
errorand retried on the next tick. The expected refusals are not errors: a 402 logs awarnand retries every five minutes, a switched-off environment logs onewarnand retries every five minutes, and a quarantine calls the observer’sonQuarantinedand waits forexpiresAt. Cache served throughout. - SSE transport errors - exponential backoff, and after three in a row the cooldown schedule. No exception.
304 Not Modified- treated as success; TTL reset.- Missing config / flag -
getConfigreturnsundefined;getFlagreturns thedefaultValue. - Unknown key in
evaluateFlags- resolves tofalseper 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
Slug doesn’t match key (Double-Gate failure)
In production, the backend validates that the slug embedded inendpoint matches the API key’s service. A mismatch returns 401 - same surface as above.
Network down at startup
If the Nexus backend is unreachable whencreate() runs, you get NexusInitError whose cause is a transport-level Error (ECONNREFUSED, ENOTFOUND, etc.).
Reading a secret with a public key
Reading a secret that doesn’t exist
Reading a non-existent flag or config
Returns the default - no error:SSE-specific behaviour
SSE failures never propagate to your code. The SDK logs them and, after three in a row, retries on the cooldown schedule while TTL polling keeps the cache fresh. To detect “live updates are no longer available”, checkclient.streamStatus:
