Enum JobError 

pub enum JobError {
    Retryable(Box<dyn Error + Send + Sync + 'static>),
    Fatal(Box<dyn Error + Send + Sync + 'static>),
    Deferred {
        delay: Duration,
        reason: String,
    },
}

Error returned by a crate::JobHandler.

Variants

Retryable(Box<dyn Error + Send + Sync + 'static>)

Transient failure; the retry policy decides whether to retry.

Fatal(Box<dyn Error + Send + Sync + 'static>)

Permanent failure; go straight to dead-letter regardless of policy.

Deferred

Not a failure: the job could not run yet and must be tried again in delay.

The motivating case is an external API answering 429 Too Many Requests with Retry-After: 30: nothing went wrong. The job has to wait exactly that long and then run before the backlog that piled up meanwhile.

Unlike JobError::Retryable:

• crate::Envelope::attempt is unchanged, so a deferral never burns down the retry budget and a job may defer itself indefinitely;
• the retry policy is not consulted: neither its backoff (the handler states the delay) nor its max_attempts (nothing failed, so nothing is dead-lettered);
• crate::Envelope::deferrals is incremented and the envelope comes back with the highest priority its queue supports, ahead of normally enqueued work;
• the worker logs it at INFO, not WARN/ERROR.

There is no built-in cap: a handler that wants one inspects crate::JobContext::deferrals and returns JobError::Fatal instead.

Fields

delay: Duration

How long the job must wait before it is delivered again.

reason: String

Why it was deferred, for logs. Not part of any control flow.

Implementations

impl JobError

pub fn retryable<E: Error + Send + Sync + 'static>(e: E) -> Self

Wrap e as a transient failure.

pub fn fatal<E: Error + Send + Sync + 'static>(e: E) -> Self

Wrap e as a permanent failure.

pub fn retryable_msg(msg: impl Into<String>) -> Self

Transient failure with a plain message.

pub fn fatal_msg(msg: impl Into<String>) -> Self

Permanent failure with a plain message.

pub fn deferred(delay: Duration) -> Self

Defer the job by delay with the generic reason "deferred".

Not a failure: the attempt counter is untouched and the retry policy is not consulted. See JobError::Deferred.

pub fn deferred_msg(delay: Duration, msg: impl Into<String>) -> Self

Defer the job by delay, recording why ("rate limited: Retry-After 30s").

Not a failure: the attempt counter is untouched and the retry policy is not consulted. See JobError::Deferred.

Trait Implementations

impl Debug for JobError

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

Formats the value using the given formatter.

impl Display for JobError

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

Formats the value using the given formatter.

impl Error for JobError

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<Box<dyn Error + Sync + Send>> for JobError

Convenience: any std::error::Error becomes a retryable job error.

fn from(e: Box<dyn Error + Send + Sync + 'static>) -> Self

Converts to this type from the input type.