Skip to main content
The SDK distinguishes between two classes of failures:
  1. Initial sync failures - thrown from NexusClient.create(), so in a Spring application the context fails to start. That is the correct behaviour for a configuration source.
  2. Background refresh and stream failures - never thrown. They are logged, the cache keeps serving, and the SDK retries on its own.

Exception hierarchy

Every SDK exception extends NexusException, which is unchecked. A single catch covers all of them:

When each is thrown

What is not thrown

  • Background refresh failures - logged at ERROR, the cache keeps serving, the next read after the TTL retries.
  • Stream failures - backoff, then the reconnect cooldown; see SSE live updates.
  • 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 - getConfig returns Optional.empty(); getFlag returns the default.

Failure scenarios

Wrong API key

The Spring context fails to start:
An application with no config has no defined behaviour and should not accept traffic; a context that fails to start is never reported healthy.

Network down at startup

If the Nexus backend is unreachable when the client is created, a bean of your own can retry:

The environment is switched off

An API error you want to branch on

Stream health

Stream failures never reach your code. To report whether live updates are flowing, a health indicator can read isStreamConnected():
A disconnected stream leaves the cache current through polling, so it is reported as a detail rather than as DOWN.