Rust SDK - Error handling

NexusError

#[non_exhaustive]
pub enum NexusError {
    Config(String),
    Unauthorized,
    BadRequest,
    Forbidden,
    NotFound,
    PublicKeyRestricted,
    ServiceKindMismatch,
    SecretNotFound(String),
    SyncFailed(String),
    Billing,
    RateLimited,
    Quarantined { reason: String, expires_at: String },
    WifNotConfigured,
    WifTokenExchangeFailed(String),
    DeveloperCredentials(String),
    SessionExpired,
    AbAddonNotAvailable,
    ResponseTooLarge { limit: usize },
    Transport(Box<dyn std::error::Error + Send + Sync>),
    Json(serde_json::Error),
    Io(std::io::Error),
}

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

Variant	HTTP	Meaning
`Config`	-	A configuration value was rejected at construction; the message names the option and, for lists, the index
`Unauthorized`	401	Credential rejected
`BadRequest`	400	Malformed request body (token exchange)
`Forbidden`	403	Understood but refused - e.g. WIF not enabled for this service
`NotFound`	404	Resource does not exist
`PublicKeyRestricted`	-	A public key attempted a secret operation - no HTTP call was made
`ServiceKindMismatch`	-	Secrets requested on a `frontend`-kind service
`SecretNotFound`	-	Absent from the snapshot, or the entry is file-type; the key is truncated to 128 chars
`SyncFailed`	-	Unexpected status, or a response that does not match the contract
`Billing`	402	Overdue invoices; the background refresh backs off, cached values keep being served
`RateLimited`	429	Rate limited, no quarantine body
`Quarantined`	429	Quarantined by anomaly detection; do not retry until `expires_at`
`WifNotConfigured`	-	WIF requested but no provider detected
`WifTokenExchangeFailed`	-	The exchange failed, or the configured token source failed or panicked
`DeveloperCredentials(String)`	-	A `westyx dev setup` credential was found but cannot be used - expired, malformed, or readable by other local users. The message names the command or `chmod` that fixes it, and never carries the token
`SessionExpired`	-	The session expired and a refresh produced none
`AbAddonNotAvailable`	403	The AB Testing add-on is not active
`ResponseTooLarge`	-	A response body exceeded the size the SDK will buffer
`Transport`	-	Transport or TLS failure; the concrete type is erased on purpose
`Json`	-	The body was not valid JSON
`Io`	-	Filesystem failure while materialising a file-type secret

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 status means the same thing wherever you hit it. No error message ever embeds a response body.

Matching

use westyx_nexus::{ExposeSecret, NexusError};

match client.get_secret("MY_SECRET") {
    Ok(value) => println!("{} bytes", value.expose_secret().len()),
    Err(NexusError::PublicKeyRestricted) => eprintln!("public keys cannot read secrets"),
    Err(NexusError::ServiceKindMismatch) => eprintln!("frontend services hold no secrets"),
    Err(NexusError::SecretNotFound(key)) => eprintln!("no such secret: {key}"),
    Err(NexusError::Billing) => eprintln!("tenant has overdue invoices"),
    Err(NexusError::RateLimited) => eprintln!("rate limited - back off"),
    Err(e) => eprintln!("error: {e}"),
}

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:

use std::error::Error;

if let Err(err) = client.sync().await {
    if let Some(source) = err.source() {
        eprintln!("caused by: {source}");
        if let Some(e) = source.downcast_ref::<reqwest::Error>() {
            eprintln!("timeout: {}", e.is_timeout());
        }
    }
}

Configuration errors

invalid configuration: `ttl` is 0ns, which is below the 1s minimum - a zero or
sub-second TTL makes every read trigger a refresh

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:

tracing_subscriber::fmt().with_max_level(tracing::Level::DEBUG).init();

No span field or event ever carries a secret value, a secret key name, an API key, a session JWT or a workload OIDC token.

Overview

Backend SDKs

Browser SDKs

OpenFeature Providers

Rust SDK - Error handling

NexusError

One mapping for every endpoint

Matching

429: quarantine vs rate limit

Reaching the transport error

Configuration errors

What never fails

Background errors

​NexusError

​One mapping for every endpoint

​Matching

​429: quarantine vs rate limit

​Reaching the transport error

​Configuration errors

​What never fails

​Background errors

NexusError

One mapping for every endpoint

Matching

429: quarantine vs rate limit

Reaching the transport error

Configuration errors

What never fails

Background errors