Skip to main content

NexusError

The enum is #[non_exhaustive], so include a _ arm - future variants will not break your build.

Status and code

Every error answers two questions, whatever its variant, so a caller that only needs to branch on the status does not match a dozen variants:
status() is the HTTP status the error was raised for, code() the server’s error code. A code is reported only when the server sent a plain identifier; the response body itself never reaches an error, because it can echo credential material.

One mapping for every endpoint

Sync, the write endpoints, AB evaluation, the token exchange and the stream share a single status-to-error mapping, so the same response means the same thing wherever you hit it:

Matching

A cache read makes no request, so it never returns an HTTP error: the snapshot it reads was filled by create, the background refresh or the stream.

A switched-off environment

While the environment is switched off, reads keep serving the cached snapshot. The background refresh and the stream wait five minutes between attempts, one warning is logged, and the first successful sync clears it. create, an explicit sync(), evaluate_ab and the write methods return EnvironmentDisabled; the OpenFeature provider serves the snapshot as STALE.

429: quarantine vs rate limit

  • Body {"error":"quarantined","reason":"...","expires_at":"..."} → Quarantined { reason, expires_at }. The SDK pauses syncing until expires_at (clamped to 24 hours) on both the background and the read path, and the stream waits it out without counting it as a transport error.
  • Any other 429 → RateLimited. Back off before retrying a write.

Reaching the transport error

The HTTP client is an implementation detail, so Transport erases it. Recover the concrete error through the standard error chain - the downcast needs reqwest as a dependency of your own:
SessionExpired reaches its refresh error the same way, through source().

Configuration errors

Rejections happen once, at construction, and name the option. See Configuration for the full list of rejected values.

What never fails

Cache reads cannot fail on a lock: a panic elsewhere in the process cannot poison the client’s state into permanent unavailability, so get_flag, get_all_configs and friends keep their infallible signatures.

Background errors

Errors on background paths - a failed background sync, a stream disconnect, a refused refresh, a failed file-secret write - are reported through tracing with structured fields rather than swallowed. See Logging.