Enum SzError 

#[non_exhaustive]
pub enum SzError {
    BadInput(ErrorContext),
    Configuration(ErrorContext),
    Database(ErrorContext),
    License(ErrorContext),
    NotFound(ErrorContext),
    Retryable(ErrorContext),
    Unrecoverable(ErrorContext),
    Unknown(ErrorContext),
    NotInitialized(ErrorContext),
    DatabaseConnectionLost(ErrorContext),
    DatabaseTransient(ErrorContext),
    ReplaceConflict(ErrorContext),
    RetryTimeoutExceeded(ErrorContext),
    Unhandled(ErrorContext),
    UnknownDataSource(ErrorContext),
    EnvironmentDestroyed(ErrorContext),
    Ffi(ErrorContext),
    Json(Error),
    StringConversion(NulError),
}

The error type returned by all Senzing SDK operations.

Every SDK method returns SzResult<T>, which is Result<T, SzError>. Each variant maps to a specific category of failure from the native Senzing library — see the module documentation for a guide to handling these errors.

Handling errors

You can match on specific variants, use the boolean classification methods (is_retryable(), is_bad_input(), etc.), or use is() for polymorphic hierarchy checks.

This enum is #[non_exhaustive], so always include a catch-all arm:

Examples

use sz_rust_sdk::prelude::*;

match engine.get_record("CUSTOMERS", "CUST001", None) {
    Ok(json) => println!("{json}"),
    Err(SzError::NotFound(_)) => println!("Record does not exist"),
    Err(SzError::UnknownDataSource(_)) => println!("Data source not registered"),
    Err(e) if e.is_retryable() => println!("Temporary failure, retry: {e}"),
    // Always include catch-all for non-exhaustive enums
    Err(e) => return Err(e),
}

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

BadInput(ErrorContext)

Errors related to invalid input parameters

Configuration(ErrorContext)

Configuration-related errors

Database(ErrorContext)

Database operation errors

License(ErrorContext)

License-related errors

NotFound(ErrorContext)

Resource not found errors

Retryable(ErrorContext)

Errors that indicate the operation should be retried

Unrecoverable(ErrorContext)

Unrecoverable errors that require reinitialization

Unknown(ErrorContext)

Unknown or unexpected errors

NotInitialized(ErrorContext)

System not initialized errors

DatabaseConnectionLost(ErrorContext)

Database connection lost errors

DatabaseTransient(ErrorContext)

Database transient errors (e.g., deadlocks)

ReplaceConflict(ErrorContext)

Replace conflict errors

RetryTimeoutExceeded(ErrorContext)

Retry timeout exceeded errors

Unhandled(ErrorContext)

Unhandled errors

UnknownDataSource(ErrorContext)

Unknown data source errors

EnvironmentDestroyed(ErrorContext)

Environment has been destroyed

Corresponds to SzEnvironmentDestroyedException in C# SDK. This error occurs when attempting to use an environment that has already been destroyed.

Ffi(ErrorContext)

FFI-related errors

Json(Error)

JSON serialization/deserialization errors

StringConversion(NulError)

String conversion errors (C string handling)

Implementations

impl SzError

pub fn bad_input<S: Into<String>>(message: S) -> Self

Creates a new BadInput error

pub fn configuration<S: Into<String>>(message: S) -> Self

Creates a new Configuration error

pub fn database<S: Into<String>>(message: S) -> Self

Creates a new Database error

pub fn license<S: Into<String>>(message: S) -> Self

Creates a new License error

pub fn not_found<S: Into<String>>(message: S) -> Self

Creates a new NotFound error

pub fn retryable<S: Into<String>>(message: S) -> Self

Creates a new Retryable error

pub fn unrecoverable<S: Into<String>>(message: S) -> Self

Creates a new Unrecoverable error

pub fn unknown<S: Into<String>>(message: S) -> Self

Creates a new Unknown error

pub fn ffi<S: Into<String>>(message: S) -> Self

Creates a new FFI error

pub fn not_initialized<S: Into<String>>(message: S) -> Self

Creates a new NotInitialized error

pub fn database_connection_lost<S: Into<String>>(message: S) -> Self

Creates a new DatabaseConnectionLost error

pub fn database_transient<S: Into<String>>(message: S) -> Self

Creates a new DatabaseTransient error

pub fn replace_conflict<S: Into<String>>(message: S) -> Self

Creates a new ReplaceConflict error

pub fn retry_timeout_exceeded<S: Into<String>>(message: S) -> Self

Creates a new RetryTimeoutExceeded error

pub fn unhandled<S: Into<String>>(message: S) -> Self

Creates a new Unhandled error

pub fn unknown_data_source<S: Into<String>>(message: S) -> Self

Creates a new UnknownDataSource error

pub fn environment_destroyed<S: Into<String>>(message: S) -> Self

Creates a new EnvironmentDestroyed error

pub fn find_in_chain<'a>(err: &'a (dyn Error + 'static)) -> Option<&'a SzError>

Finds the first SzError in an error’s source() chain.

Checks the error itself first via downcast_ref, then iteratively walks the source() chain. Returns None if no SzError is found anywhere in the chain.

When to use this vs SzErrorInspect

In most cases, prefer the SzErrorInspect trait methods (is_sz_retryable(), sz_error(), etc.) — they call this internally and provide a cleaner API. Use find_in_chain directly when you have a bare &dyn Error reference and the trait is not in scope, or in generic contexts where the trait bound is awkward.

Examples

use sz_rust_sdk::error::SzError;

// No SzError in an io::Error
let io_err: Box<dyn std::error::Error> =
    Box::new(std::io::Error::new(std::io::ErrorKind::NotFound, "missing"));
assert!(SzError::find_in_chain(io_err.as_ref()).is_none());

// SzError found directly
let sz_err: Box<dyn std::error::Error> =
    Box::new(SzError::database_transient("Deadlock"));
let found = SzError::find_in_chain(sz_err.as_ref()).unwrap();
assert!(found.is_retryable());
assert_eq!(found.category(), "database_transient");

pub fn error_code(&self) -> Option<i64>

Returns the native Senzing error code, if available.

Most errors returned by the SDK carry the numeric code from getLastExceptionCode(). Use this for logging, metrics, or when you need to look up a specific code in the Senzing documentation.

Examples

use sz_rust_sdk::prelude::*;

if let Err(e) = engine.add_record("TEST", "1", "{}", None) {
    if let Some(code) = e.error_code() {
        eprintln!("Senzing error code {code}: {e}");
    }
}

pub fn component(&self) -> Option<SzComponent>

Returns the SDK component that generated this error.

Indicates which Senzing subsystem (Engine, Config, ConfigMgr, Diagnostic, Product) produced the error. Useful for targeted logging or diagnostics.

Examples

use sz_rust_sdk::prelude::*;
use sz_rust_sdk::error::SzComponent;

if let Err(e) = engine.add_record("TEST", "1", "{}", None) {
    if let Some(component) = e.component() {
        eprintln!("Error from {:?}: {e}", component);
    }
}

pub fn message(&self) -> &str

Returns the error message without the error type prefix.

This gives you the raw message from the native Senzing library, without the “Bad input: “ or “Database error: “ prefix that Display adds.

Examples

use sz_rust_sdk::prelude::*;

if let Err(e) = engine.get_record("TEST", "MISSING", None) {
    eprintln!("message: {}", e.message());
    eprintln!("display: {e}");  // includes type prefix
}

pub fn is_retryable(&self) -> bool

Returns true if this error indicates the operation should be retried

This includes Retryable and its subtypes:

• DatabaseConnectionLost
• DatabaseTransient
• RetryTimeoutExceeded

Examples

use sz_rust_sdk::error::SzError;

let error = SzError::database_connection_lost("Connection lost");
assert!(error.is_retryable());

pub fn is_unrecoverable(&self) -> bool

Returns true if this error is unrecoverable

This includes Unrecoverable and its subtypes:

• Database
• License
• NotInitialized
• Unhandled

Examples

use sz_rust_sdk::error::SzError;

let error = SzError::license("License expired");
assert!(error.is_unrecoverable());

pub fn is_bad_input(&self) -> bool

Returns true if this error is a bad input error

This includes BadInput and its subtypes:

• NotFound
• UnknownDataSource

Examples

use sz_rust_sdk::error::SzError;

let error = SzError::not_found("Entity not found");
assert!(error.is_bad_input());

pub fn is_database(&self) -> bool

Returns true if this is a database-related error

This includes ALL database errors regardless of retryability:

• Database (unrecoverable)
• DatabaseConnectionLost (retryable)
• DatabaseTransient (retryable)

Examples

use sz_rust_sdk::error::SzError;

// Unrecoverable database error
let error = SzError::database("Schema error");
assert!(error.is_database());
assert!(error.is_unrecoverable());

// Retryable database error
let error = SzError::database_transient("Deadlock");
assert!(error.is_database());
assert!(error.is_retryable());

pub fn is_license(&self) -> bool

Returns true if this is a license-related error

Examples

use sz_rust_sdk::error::SzError;

let error = SzError::license("License expired");
assert!(error.is_license());

pub fn is_configuration(&self) -> bool

Returns true if this is a configuration-related error

Examples

use sz_rust_sdk::error::SzError;

let error = SzError::configuration("Invalid config");
assert!(error.is_configuration());

pub fn is_initialization(&self) -> bool

Returns true if this is an initialization-related error

Examples

use sz_rust_sdk::error::SzError;

let error = SzError::not_initialized("SDK not initialized");
assert!(error.is_initialization());

pub fn hierarchy(&self) -> Vec<ErrorCategory>

Returns this error’s type hierarchy from most specific to least

This makes parent-child relationships explicit and queryable at runtime. The first element is always the most specific type, followed by parent categories in order.

Examples

use sz_rust_sdk::error::{SzError, ErrorCategory};

let err = SzError::database_transient("Deadlock");

// Get the full hierarchy
let hierarchy = err.hierarchy();
assert_eq!(hierarchy, vec![
    ErrorCategory::DatabaseTransient,
    ErrorCategory::Retryable,
]);

// Check if error "is a" Retryable (polymorphic check)
assert!(err.is(ErrorCategory::Retryable));
assert!(err.is(ErrorCategory::DatabaseTransient));

pub fn is(&self, category: ErrorCategory) -> bool

Checks if this error belongs to a category (polymorphic check)

This checks the entire hierarchy, so DatabaseTransient will return true for both ErrorCategory::DatabaseTransient and ErrorCategory::Retryable.

Examples

use sz_rust_sdk::error::{SzError, ErrorCategory};

let err = SzError::database_transient("Deadlock");

// Check specific type
assert!(err.is(ErrorCategory::DatabaseTransient));

// Check parent category (polymorphic)
assert!(err.is(ErrorCategory::Retryable));

// Not in this category
assert!(!err.is(ErrorCategory::BadInput));

pub fn category(&self) -> &'static str

Returns the error category as a string.

Useful for structured logging, metrics, and error reporting systems that categorize errors by type.

Examples

use sz_rust_sdk::prelude::*;

if let Err(e) = engine.add_record("TEST", "1", "{}", None) {
    eprintln!("[{}] {}", e.category(), e);
    // e.g. "[bad_input] Bad input: ..."
}

pub fn severity(&self) -> &'static str

Returns the severity level of this error.

Severity levels:

• "critical": License failures, unhandled errors
• "high": Database errors, not initialized
• "medium": Connection issues, transient errors, configuration
• "low": Input validation, not found

Examples

use sz_rust_sdk::prelude::*;

if let Err(e) = engine.add_record("TEST", "1", "{}", None) {
    eprintln!("[{}:{}] {}", e.severity(), e.category(), e);
}

pub fn from_code_with_message(error_code: i64, component: SzComponent) -> Self

Creates an error from getLastExceptionCode() with message from getLastException()

This method maps native Senzing error codes to the appropriate Rust error type. The mapping is auto-generated from szerrors.json and covers all 456 Senzing error codes.

Examples

use sz_rust_sdk::error::{SzError, SzComponent};

let error = SzError::from_code_with_message(999, SzComponent::Engine);
assert!(matches!(error, SzError::License(_)));
assert_eq!(error.error_code(), Some(999));

fn get_last_exception_message(component: SzComponent, error_code: i64) -> String

Gets the last exception message from the specified component

pub fn from_code(error_code: i64) -> Self

Creates an error from getLastExceptionCode() (legacy method for compatibility)

pub fn from_source(source: Box<dyn Error + Send + Sync>) -> Self

Creates an Unknown error from a source error

pub fn with_message_and_source<S: Into<String>>( message: S, source: Box<dyn Error + Send + Sync>, ) -> Self

Creates an Unknown error with a custom message and source

impl SzError

pub fn with_source<E>(self, source: E) -> Self

where E: Error + Send + Sync + 'static,

Adds a source error to this error (builder pattern)

Examples

use sz_rust_sdk::error::SzError;

fn parse_config(data: &str) -> Result<(), SzError> {
    let json_result: Result<serde_json::Value, _> = serde_json::from_str(data);
    json_result.map_err(|e|
        SzError::configuration("Invalid JSON config")
            .with_source(e)
    )?;
    Ok(())
}

Trait Implementations

impl Debug for SzError

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

Formats the value using the given formatter.

impl Display for SzError

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

Formats the value using the given formatter.

impl Error for SzError

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<Error> for SzError

fn from(err: Error) -> Self

Converts to this type from the input type.

impl From<NulError> for SzError

fn from(err: NulError) -> Self

Converts to this type from the input type.