Enum SdkError 

pub enum SdkError {
    Backend(BackendError),
    BackendContext {
        source: BackendError,
        context: String,
    },
    Engine(Box<EngineError>),
    Config {
        context: String,
        field: Option<String>,
        message: String,
    },
    WorkerAtCapacity,
    Http {
        source: Error,
        context: String,
    },
    AdminApi {
        status: u16,
        message: String,
        kind: Option<String>,
        retryable: Option<bool>,
        raw_body: String,
    },
}

SDK error type.

Variants

Backend(BackendError)

Backend transport error. Previously wrapped ferriskey::Error directly (#88); now carries a backend-agnostic BackendError so consumers match on BackendErrorKind instead of ferriskey’s native taxonomy. The ferriskey → BackendError mapping lives in ff_backend_valkey::backend_error::backend_error_from_ferriskey.

BackendContext

Backend error with additional context (e.g. call-site label). Previously ValkeyContext { source: ferriskey::Error } (#88).

Fields

source: BackendError

context: String

Engine(Box<EngineError>)

FlowFabric engine error — typed sum over Lua error codes + transport faults. See EngineError for the variant-granularity contract. Replaces the previous Script(ScriptError) carrier (#58.6).

Boxed to keep SdkError’s stack footprint small: the richest variant (ConflictKind::DependencyAlreadyExists { existing: EdgeSnapshot }) is ~200 bytes. Boxing keeps Result<T, SdkError> at the same width every other variant pays.

Config

Configuration error. context identifies the call site / logical operation (e.g. "describe_execution: exec_core", "admin_client"). field names the specific offending field when the error is field-scoped (e.g. Some("public_state")), or None for whole-object validation (e.g. "at least one lane is required"). message carries dynamic detail: source-error rendering, the offending raw value, etc.

Fields

context: String

field: Option<String>

message: String

WorkerAtCapacity

Worker is at its configured max_concurrent_tasks capacity — the caller should retry later. Returned by FlowFabricWorker::claim_from_grant and FlowFabricWorker::claim_from_reclaim_grant when the concurrency semaphore is saturated. Distinct from Ok(None): a ClaimGrant/ReclaimGrant represents real work already selected by the scheduler, so silently dropping it would waste the grant and let the grant TTL elapse. Surfacing the saturation lets the caller release the grant (or wait + retry).

Classification

• SdkError::is_retryable returns true — saturation is transient: any in-flight task’s complete/fail/cancel/drop releases a permit. Retry after milliseconds, not a retry loop with backoff for a backend transport failure.
• SdkError::backend_kind returns None — this is not a backend transport error, so there is no BackendErrorKind to inspect. Callers that fan out on backend_kind() should match WorkerAtCapacity explicitly (or use is_retryable()).

Http

HTTP transport error from the admin REST surface. Carries the underlying reqwest::Error via #[source] so callers can inspect is_timeout() / is_connect() / etc. for finer-grained retry logic. Distinct from SdkError::Backend — this fires on the HTTP/JSON surface, not on the Lua/Valkey hot path.

Fields

source: Error

context: String

AdminApi

The admin REST endpoint returned a non-2xx response.

Fields surface the server-side ErrorBody JSON shape ({ error, kind?, retryable? }) as structured values so cairn-fabric and other consumers can match without re-parsing the body:

• status — HTTP status code.
• message — the error string from the JSON body (or the raw body if it didn’t parse as JSON).
• kind — server-supplied Valkey ErrorKind label for 5xxs backed by a transport error; None for 4xxs.
• retryable — server-supplied hint; None for 4xxs.
• raw_body — the full response body, preserved for logging when the JSON shape doesn’t match.

Fields

status: u16

message: String

kind: Option<String>

retryable: Option<bool>

raw_body: String

Implementations

impl SdkError

pub fn backend_kind(&self) -> Option<BackendErrorKind>

Returns the classified BackendErrorKind if this error carries a backend transport fault. Covers the direct SdkError::Backend / SdkError::BackendContext variants and Engine(EngineError::Transport { .. }) via the ScriptError-aware downcast in ff_script::engine_error_ext.

Renamed from valkey_kind in #88 — the previous return type Option<ferriskey::ErrorKind> leaked ferriskey into every consumer doing retry classification.

pub fn is_retryable(&self) -> bool

Whether this error is safely retryable by a caller. For backend transport variants, delegates to BackendErrorKind::is_retryable. For Engine errors, returns true iff the typed classification is ErrorClass::Retryable. Config errors are never retryable.

Trait Implementations

impl Debug for SdkError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for SdkError

fn fmt(&self, __formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for SdkError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<BackendError> for SdkError

fn from(source: BackendError) -> Self

Converts to this type from the input type.

impl From<EngineError> for SdkError

fn from(err: EngineError) -> Self

Converts to this type from the input type.

impl From<Error> for SdkError

Available on crate feature valkey-default only.

Lift a native ferriskey::Error into SdkError::Backend via ff_backend_valkey::backend_error_from_ferriskey (#88). Keeps ?-propagation ergonomic at FCALL/transport call sites while the public variant stays backend-agnostic.

fn from(err: Error) -> Self

Converts to this type from the input type.

impl From<ScriptError> for SdkError

Preserves the ergonomic ?-propagation from FCALL sites that return Result<_, ScriptError>. Routes through EngineError’s typed classification so every call site gets the same variant-level detail without hand-written conversion.

fn from(err: ScriptError) -> Self

Converts to this type from the input type.