Skip to main content
All SDK exceptions extend NexusException, which extends RuntimeException. Catch the base class to handle every SDK error in one place, or a subclass for fine-grained control. Two classes of failure behave differently:
  1. Creating the client - NexusClient.create throws, so a service with no configuration does not start.
  2. Background refresh and stream failures - never thrown. They are logged, the cache keeps serving, and the SDK retries on its own.

Exception reference

One mapping, every endpoint

/v1/sync, /v1/flags/evaluate-ab, the three secret-write endpoints, the stream and the token exchange share one status-to-exception mapping, so the same server response produces the same exception whichever call made it: On the stream a refusal is not thrown: a switched-off environment moves it to the cooldown schedule, anything else counts as a transport error. See SSE live updates.

What is not thrown

  • Background refresh failures - logged at warn, the cache keeps serving, the next read after the TTL retries.
  • Stream failures - backoff, then the reconnect cooldown.
  • A failed WIF refresh while the session is still valid - logged at warn; the request goes out with the current session.
  • 304 Not Modified - a successful sync.
  • A missing config or flag - the getter returns your default.

Catching exceptions at client creation

create wraps a failure of the initial sync or session exchange in NexusInitException; read its cause:

Catching secret access errors

Catching A/B errors

Branching on an API error

Catching write API errors

Quarantine

When a request receives a quarantine response (HTTP 429 with "error": "quarantined"), the SDK throws NexusQuarantinedException and also calls observer.onQuarantined(reason, expiresAt). The stream waits until expiresAt and reconnects without consuming its failure budget. The deadline is clamped to at most 24 hours from now, and a deadline in the past collapses to now, so both the exception and the observer callback carry a bound you can schedule against.