.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 at Error level through the SDK’s ILogger, and the existing cache continues to be served.

Exception hierarchy

All SDK exceptions extend NexusException directly - there is no further nesting. 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)
    ├── NexusConfigException                  (a NexusConfig value cannot be meant - v0.14.0)
    ├── NexusUnauthorizedException            (HTTP 401)
    ├── NexusNotFoundException                (HTTP 404)
    ├── NexusBillingException                 (HTTP 402 - overdue invoices - v0.2.0)
    ├── NexusRateLimitedException             (HTTP 429 write rate limit - v0.5.0)
    ├── NexusQuarantinedException             (HTTP 429 quarantine body - v0.4.0)
    ├── NexusApiException                     (an unexpected/unmapped HTTP status)
    ├── NexusPublicKeyException               (public key tried to read a secret)
    ├── NexusServiceKindMismatchException     (secret access on a frontend service - v0.2.0)
    ├── NexusSecretNotFoundException          (key absent from cache)
    ├── NexusWifNotConfiguredException        (no WIF provider matched - v0.2.0)
    ├── NexusWifTokenExchangeFailedException  (token exchange failed - v0.2.0)
    ├── NexusSessionExpiredException          (WIF session expired - v0.2.0)
    └── NexusAbAddonNotAvailableException     (AB Testing add-on not active - v0.3.0)

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 throttles the background refresh to one attempt every five minutes and serves the last cached snapshot; any success clears it, a `304 Not Modified` included, so settling the invoice restores service without a restart. Check `client.BillingOverdue` on the client.
`NexusConfigException` (v0.14.0)	`CreateAsync()`	A configuration value cannot be meant - a non-positive `Ttl`, `StreamIdleTimeout`, `StreamConnectTimeout` or `PooledConnectionLifetime`, an empty `SseReconnectCooldown`, or a schedule entry below one minute. `Option` carries the offending property name; the message names the index for a schedule entry. Pass `null` to select a default.
`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`	`GetSecret()`, `SetSecretAsync()`, `DeleteSecretAsync()`, `DeleteSecretVersionAsync()`	The client was created with a public key, or the backend reports the key as public.
`NexusServiceKindMismatchException` (v0.2.0)	`GetSecret()`	The service `kind` reported by the server is `"frontend"`. Frontend services must not hold secrets, regardless of key type.
`NexusSecretNotFoundException`	`GetSecret()`	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.
`NexusQuarantinedException` (v0.4.0)	`CreateAsync()`, `SyncAsync()`	Server returned HTTP 429 with a `{"error":"quarantined"}` body. `Reason` carries the server’s reason string and `ExpiresAt` the timestamp sync resumes at; the SDK also suppresses sync and fires `IStreamObserver.OnQuarantined` until then.
`NexusApiException`	`SyncAsync()`, the SSE stream, `EvaluateABAsync()`	An unexpected/unmapped HTTP status, or a response body that could not be decoded.

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_...",
});

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

Reading a secret that doesn’t exist

try
{
    client.GetSecret("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