Enum ThrottleError 

#[non_exhaustive]
pub enum ThrottleError {
    CostExceedsCapacity {
        cost: u32,
        capacity: u32,
    },
    CircuitOpen {
        retry_after: Duration,
    },
    QueueFull,
    DeadlineExceeded,
}

Available on crate feature std only.

An acquisition that cannot complete.

The enum is #[non_exhaustive]: later phases introduce new failure modes (deadlines, a tripped circuit breaker, a closed limiter), so a match on it must include a wildcard arm.

Examples

use throttle_net::{Throttle, ThrottleError};

// Capacity is 5; asking for 9 can never be satisfied.
let throttle = Throttle::per_second(5);
let err = throttle.acquire_with_cost(9).await.unwrap_err();
assert!(matches!(err, ThrottleError::CostExceedsCapacity { cost: 9, capacity: 5 }));

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.

CostExceedsCapacity

The requested cost is larger than the limiter’s capacity, so the bucket can never hold enough tokens to grant it. Reduce the cost or raise the limiter’s capacity. This is a configuration mismatch, not a transient condition, so it is not retryable.

Fields

cost: u32

The number of tokens the caller asked for.

capacity: u32

The limiter’s maximum capacity, which cost exceeded.

CircuitOpen

A circuit breaker is open and shed this request without touching the wrapped limiter. The breaker is failing fast to give the downstream time to recover; retry once it has had a chance to close again. This is retryable, after the suggested wait.

Fields

retry_after: Duration

How long until the breaker is expected to allow a trial request (move to half-open). Duration::ZERO means it may already be admitting a trial.

QueueFull

A bounded queue was full and its overflow policy rejected this request. Transient — capacity may free up — so it is retryable.

DeadlineExceeded

A queued request’s deadline passed before it could be served. Not retryable as-is: the deadline is in the past.

Trait Implementations

impl Clone for ThrottleError

fn clone(&self) -> ThrottleError

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for ThrottleError

impl Debug for ThrottleError

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

Formats the value using the given formatter.

impl Display for ThrottleError

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

Formats the value using the given formatter.

impl Eq for ThrottleError

impl Error for ThrottleError

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 ForgeError for ThrottleError

fn kind(&self) -> &'static str

Returns the kind of error, typically matching the enum variant

fn caption(&self) -> &'static str

Returns a human-readable caption for the error

fn is_retryable(&self) -> bool

Returns true if the operation can be retried

fn is_fatal(&self) -> bool

Returns true if the error is fatal and should terminate the program

fn status_code(&self) -> u16

Returns an appropriate HTTP status code for the error

fn exit_code(&self) -> i32

Returns an appropriate process exit code for the error

fn user_message(&self) -> String

Returns a user-facing message that can be shown to end users

fn dev_message(&self) -> String

Returns a detailed technical message for developers/logs

fn backtrace(&self) -> Option<&Backtrace>

Returns a backtrace if available

fn register(&self)

Registers the error with the central error registry

impl PartialEq for ThrottleError

fn eq(&self, other: &ThrottleError) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl StructuralPartialEq for ThrottleError