Skip to main content
The SDK distinguishes between two classes of failures:
  1. Initial sync failures - surfaced as a non-nil error from NewClient. Refuse to start the application; an empty cache is unsafe to serve.
  2. Background sync / SSE failures - never returned to the caller. They are logged at Error level and the existing cache continues to be served. Use a StreamObserver to react to stream transitions programmatically, and StreamConnected() to ask whether live updates are arriving right now.

Sentinel errors

The SDK exports the following sentinel error variables. Always check with errors.Is(err, ...) rather than equality or string matching:
A status with no sentinel of its own is returned as an *APIError, which carries the HTTP status and the server’s machine-readable code. Reach it with errors.As:
This is idiomatic Go - sentinel errors compose cleanly with errors.Is and errors.As, and they’re the way io.EOF, os.ErrNotExist, sql.ErrNoRows, etc. work in the standard library.

When each is returned

What is NOT returned as an error

  • Background syncs - logged at Error and retried on the next read after a backoff (1 s doubling to 60 s). Cache served.
  • SSE transport errors - exponential backoff, then after three consecutive failures the cooldown schedule. The stream goroutine keeps running until Close.
  • 304 Not Modified - treated as success; TTL reset.
  • Missing config / flag - GetConfig returns (nil, false); GetFlag returns the defaultValue.
The asymmetry between secrets (return error) and configs/flags (return ok/default) is deliberate: a missing secret usually means “you’re misconfigured, fail fast”, while a missing flag usually means “use the safe default and continue”.

402 Payment Required - ErrBilling

When the backend returns HTTP 402 (the tenant has at least one invoice overdue by more than 14 days), the SDK:
  1. Marks the client’s billing-overdue flag (client.BillingOverdue() == true).
  2. Throttles the background refresh to one attempt every five minutes - read methods continue to serve the last cached snapshot, and settling the invoice restores service without a restart.
  3. Returns ErrBilling from Sync(...).
The flag clears automatically as soon as a subsequent Sync succeeds.

WIF-specific errors

When WIFConfig.Enabled is true:
  • ErrWIFNotConfigured - the configured (or auto-detected) provider isn’t usable in the current environment. Either the K8s service-account token file is missing, the AWS_WEB_IDENTITY_TOKEN_FILE env var isn’t set, or the GCP/Azure metadata endpoint isn’t reachable. Pass an explicit TokenSource to bypass auto-detection.
  • ErrWIFTokenExchangeFailed - the backend rejected the OIDC token, or the response could not be decoded. Inspect the wrapped error for the HTTP status. Most often caused by an audience mismatch or a clock skew between the provider and the Nexus backend.
  • ErrSessionExpired - the session has expired, its refresh failed, and no static APIKey is configured. It wraps the refresh error. A refresh that fails while the session is still valid is logged and the session keeps carrying requests until it expires. Provide both WIF and APIKey if you need automatic fallback in degraded conditions.

ErrServiceKindMismatch (frontend services)

GetSecret(...) on a service whose kind is "frontend" returns ErrServiceKindMismatch. Check client.Kind() to know the kind:

Failure scenarios

Wrong API key

ErrSyncFailed is the outer error; the cause is wrapped - errors.Is(err, nexus.ErrUnauthorized) matches transitively.

Slug doesn’t match key (Double-Gate failure)

In production, the backend validates that the slug embedded in BaseURL matches the API key’s service. A mismatch returns 401 - same surface as above.

Network down at startup

If the Nexus backend is unreachable when NewClient runs, the function returns an error wrapping ErrSyncFailed whose cause is a *url.Error. The decision is yours: crash, or wrap with retry/backoff.

Reading a secret with a public key

This check fires synchronously, before the network call.

Reading a secret that doesn’t exist

SSE-specific behaviour

Stream failures never reach your code as errors. The stream goroutine NewClient starts keeps running until Close (or the context it was started with ends): a transport error is retried on a backoff, three in a row move it to the cooldown schedule, and it reconnects on its own. The SDK logs each step:
To know whether live updates are arriving right now, read client.StreamConnected(); to react to each transition, pass a StreamObserver.