Enum SdkError 

pub enum SdkError {
    Valkey(Error),
    ValkeyContext {
        source: Error,
        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

Valkey(Error)

Valkey connection or command error (preserves ErrorKind for caller inspection).

ValkeyContext

Valkey error with additional context.

Fields

source: Error

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 Valkey transport failure.
• SdkError::valkey_kind returns None — this is not a Valkey transport or Lua error, so there is no ferriskey::ErrorKind to inspect. Callers that fan out on valkey_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::Valkey — 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 valkey_kind(&self) -> Option<ErrorKind>

Returns the underlying ferriskey ErrorKind if this error carries one. Covers transport variants (Valkey, ValkeyContext) directly and Engine(EngineError::Transport { .. }) via delegation.

pub fn is_retryable(&self) -> bool

Whether this error is safely retryable by a caller. For transport variants, delegates to ff_script::retry::is_retryable_kind. 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<EngineError> for SdkError

fn from(err: EngineError) -> Self

Converts to this type from the input type.

impl From<Error> for SdkError

fn from(source: 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.