Skip to main content
Every error the SDK raises extends NexusError, carries a stable name, and survives instanceof after transpilation.

The hierarchy

Which of these you will actually see

Most of them are handled inside the SDK and never surface. At startup - NexusConfigError for a mistake in the options, or NexusInitError if the first sync fails. In local development without a key, a NexusDevSessionError on its cause says why the developer session could not be obtained. Both are worth surfacing to the developer; neither is a runtime condition to design around. From AB evaluation - NexusAbAddonNotAvailableError when the add-on is not active. Fall back to the cached flag. A switched-off environment - when the project switches the service’s environment off, the server answers 403 environment_disabled. Reads keep returning the last snapshot; the refresh waits five minutes between attempts and the stream moves to its polling schedule, reporting environment-disabled to the observer. The first sync that succeeds after the environment is switched on restores both. NexusEnvironmentDisabledError reaches your code from an explicit sync, from AB evaluation, and from the initial sync on NexusInitError.cause. A locked-down service - when a service is in emergency lockdown, the server answers 423 service_locked. Reads keep returning the last snapshot; the stream exits immediately with service-locked fallback and background sync retries halt until an explicit sync() succeeds after the lockdown is lifted. NexusServiceLockedError reaches your code from an explicit sync, from AB evaluation, and from the initial sync on NexusInitError.cause. Everything else is absorbed. A 5xx is retried, a 429 is waited out, a 402 slows the refresh loop, a timeout is retried. Throughout, reads keep returning the last good snapshot, so there is nothing for the application to do.

Billing

A 402 does not stop the client. Reads keep being served from the snapshot, and the refresh loop slows to one attempt every five minutes rather than halting - so the client recovers on its own once the invoice is settled, with nothing to restart. Surface it passively if you want to:

Public keys and secrets

A browser client holds a public key and never accesses secrets at all - there is no getSecret() method here, and no configuration that makes one reachable from a browser. Secrets belong in a backend SDK.

Errors do not leak key material

A configuration rejection naming the API key carries only its prefix. A server error carries at most a 256-character body snippet. No error message contains a secret’s value or a secret’s key name.