.NET SDK - Error Handling

The SDK distinguishes between two classes of failures:

Initial sync failures - surfaced as exceptions. The application context refuses to start with an empty cache.
Background sync / SSE failures - never thrown. They are logged via INexusLogger.Error(...), and the existing cache continues to be served.

Exception hierarchy

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

try
{
    var client = await NexusClient.CreateAsync(config);
}
catch (NexusException ex)
{
    Console.Error.WriteLine($"Nexus failed: {ex.Message}");
    Console.Error.WriteLine($"Cause: {ex.InnerException?.Message}");
    Environment.Exit(1);
}

The full hierarchy:

Exception
└── NexusException                       (abstract base)
    ├── NexusInitException               (initial sync failure)
    ├── NexusUnauthorizedException       (HTTP 401)
    ├── NexusNotFoundException           (HTTP 404)
    ├── NexusRateLimitedException        (HTTP 429 write rate limit - v0.5.0)
    ├── NexusPublicKeyException          (public key tried to read a secret)
    └── NexusSecretNotFoundException     (key absent from cache)

When each is thrown

Exception	Thrown by	When
`NexusInitException`	`CreateAsync()`	The initial sync failed for any reason. `InnerException` carries the underlying cause (often `NexusUnauthorizedException` or a transport-level `HttpRequestException`).
`NexusUnauthorizedException`	`CreateAsync()`, `SyncAsync()`	Server returned HTTP 401 - invalid API key, slug/key mismatch, or revoked key.
`NexusBillingException` (v0.2.0)	`CreateAsync()`, `SyncAsync()`	Server returned HTTP 402 - tenant has invoices overdue by more than 14 days. The SDK halts background sync and serves the last cached snapshot; check `client.BillingOverdue` on the client.
`NexusNotFoundException`	`CreateAsync()`, `SyncAsync()`	Server returned HTTP 404 - unknown subdomain or missing endpoint.
`NexusRateLimitedException` (v0.5.0)	`SetSecretAsync()`, `DeleteSecretAsync()`, `DeleteSecretVersionAsync()`	Server returned HTTP 429 - write rate limit exceeded on secret modification endpoints.
`NexusPublicKeyException`	`GetSecretAsync()`, `SetSecretAsync()`, `DeleteSecretAsync()`, `DeleteSecretVersionAsync()`	The client was created with a public key. Thrown synchronously, before the network call.
`NexusServiceKindMismatchException` (v0.2.0)	`GetSecretAsync()`	The service `kind` reported by the server is `"frontend"`. Frontend services must not hold secrets, regardless of key type.
`NexusSecretNotFoundException`	`GetSecretAsync()`	The requested key is not in the cache. The exception’s `SecretKey` property carries the key that was requested.
`NexusWIFNotConfiguredException` (v0.2.0)	`CreateAsync()`	`Wif.Enabled = true` but no usable workload-identity provider matched the running environment. Wrapped in `NexusInitException` on the initial connect.
`NexusWIFTokenExchangeFailedException` (v0.2.0)	`CreateAsync()`, `SyncAsync()`	`POST /v1/auth/token-exchange` returned a non-2xx response. Wrapped in `NexusInitException` on the initial connect.
`NexusSessionExpiredException` (v0.2.0)	`SyncAsync()`	The WIF session JWT has expired and the SDK could not refresh it.
`NexusAbAddonNotAvailableException` (v0.3.0)	`EvaluateABAsync()`	Server returned HTTP 403 - the AB Testing add-on is not active for this tenant.

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.
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

try
{
    await NexusClient.CreateAsync(new NexusConfig
    {
        BaseUrl = "https://blue-ocean-a5rx7.westyx.dev",
        ApiKey  = "wxs_typo",
    });
}
catch (NexusInitException ex) when (ex.InnerException is NexusUnauthorizedException)
{
    // Handle bad credentials specifically.
}

Reading a secret with a public key

var client = await NexusClient.CreateAsync(new NexusConfig
{
    BaseUrl = "...",
    ApiKey  = "wxp_...",
});

await client.GetSecretAsync("DB_PASSWORD");
// throws NexusPublicKeyException - synchronously, no network call

Reading a secret that doesn’t exist

try
{
    await client.GetSecretAsync("does.not.exist");
}
catch (NexusSecretNotFoundException ex)
{
    Console.WriteLine($"Missing: {ex.SecretKey}");
}

SSE-specific behaviour

SSE failures never propagate to your code. The SDK logs them at Error level and keeps the cache going via TTL polling.

nexus: SSE transport error (attempt 1/3)
nexus: SSE transport error (attempt 2/3)
nexus: SSE 3 consecutive transport errors - falling back to TTL polling

If you need to react to “live updates are no longer available”, poll client.IsStreamConnected - it flips to false when the stream falls back.

Overview

Backend SDKs

Browser SDKs

OpenFeature Providers

.NET SDK - Error Handling

Exception hierarchy

When each is thrown

What is NOT thrown

Failure scenarios

Wrong API key

Reading a secret with a public key

Reading a secret that doesn’t exist

SSE-specific behaviour

​Exception hierarchy

​When each is thrown

​What is NOT thrown

​Failure scenarios

​Wrong API key

​Reading a secret with a public key

​Reading a secret that doesn’t exist

​SSE-specific behaviour

Exception hierarchy

When each is thrown

What is NOT thrown

Failure scenarios

Wrong API key

Reading a secret with a public key

Reading a secret that doesn’t exist

SSE-specific behaviour