Struct HandlerError 

pub struct HandlerError { /* private fields */ }

Reports an application-defined Step or RPC failure to Dex.

Return this error from crate::Step::wait_for, crate::Step::execute, or an RPC handler. Dex records the message and applies the configured retry or failure policy.

Every constructor captures a stack at the construction site with Backtrace::force_capture. The Worker prefers that construction-site stack over a wrap-site capture when encoding dex_protocol::dex::WorkerErrorResponse.

Prefer Self::from_error when wrapping another Error so Dex receives that concrete type name. Use Self::new when you want an explicit application error type string.

Examples

use std::error::Error;
use std::fmt::{Display, Formatter};

use dex_sdk::HandlerError;

#[derive(Debug)]
struct PaymentError;

impl Display for PaymentError {
    fn fmt(&self, formatter: &mut Formatter<'_>) -> std::fmt::Result {
        formatter.write_str("payment failed")
    }
}

impl Error for PaymentError {}

fn charge() -> Result<(), HandlerError> {
    Err(HandlerError::new("PaymentDeclined", "payment failed"))
}

fn charge_from_error() -> Result<(), HandlerError> {
    Err(HandlerError::from_error(PaymentError))
}

fn charge_with_retry() -> Result<(), HandlerError> {
    Err(HandlerError::retry_after(30, "PaymentDeclined", "payment failed"))
}

Implementations

impl HandlerError

pub fn new(error_type: impl Into<String>, message: impl Into<String>) -> Self

Creates a handler error with an explicit error type and message.

error_type is the stable label Dex stores as dex_protocol::dex::WorkerErrorResponse::error_type. Prefer a short application-specific name such as "PaymentDeclined" or a library type path. message is the developer-facing detail string.

Captures a stack at this call site so Dex can report the origin of the failure. Prefer constructing the error where the failure is detected rather than mapping it later through a distant helper.

Examples

use dex_sdk::HandlerError;

let error = HandlerError::new("PaymentDeclined", "payment failed");
assert_eq!(error.to_string(), "payment failed");

pub fn from_error<E: Error>(error: E) -> Self

Creates a handler error from another Error, preserving its type name.

Uses std::any::type_name of E as dex_protocol::dex::WorkerErrorResponse::error_type and error.to_string() as the detail. Captures a stack at this call site the same way Self::new does. Prefer this when mapping database, HTTP, or other library failures into a Dex handler failure.

Examples

use std::error::Error;
use std::fmt::{Display, Formatter};

use dex_sdk::HandlerError;

#[derive(Debug)]
struct DbError;

impl Display for DbError {
    fn fmt(&self, formatter: &mut Formatter<'_>) -> std::fmt::Result {
        formatter.write_str("connection refused")
    }
}

impl Error for DbError {}

let error = HandlerError::from_error(DbError);
assert_eq!(error.to_string(), "connection refused");

pub fn retry_after( after_seconds: i32, error_type: impl Into<String>, message: impl Into<String>, ) -> Self

Requests the next retry interval while preserving this failure.

Captures a stack at this call site the same way Self::new does. after_seconds is the delay Dex should wait before retrying the Step method. error_type is stored as dex_protocol::dex::WorkerErrorResponse::error_type. message is the failure detail reported to Dex.

Examples

use dex_sdk::HandlerError;

let error = HandlerError::retry_after(30, "PaymentDeclined", "payment failed");
assert_eq!(error.to_string(), "payment failed");

Trait Implementations

impl Debug for HandlerError

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

Formats the value using the given formatter.

impl Display for HandlerError

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

Formats the value using the given formatter.

impl Error for HandlerError

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.