Errors
Library code in distkit never panics. Anything that can go wrong comes back through a single error type, DistkitError, so ? works uniformly across counters, locks, and rate limiting.
DistkitError
pub enum DistkitError {
InvalidRedisKey(String), // a key failed validation
CounterError(CounterError), // counter operation failed (feature = "counter")
LockError(LockError), // lock operation failed (feature = "lock")
RedisError(redis::RedisError), // transport or Lua script error
MutexPoisoned(&'static str), // an internal sync primitive was poisoned
CustomError(String), // catch-all
TrypemaError(TrypemaError), // rate limiting failed (feature = "trypema")
}
The feature-gated variants only exist when the matching feature is enabled, so you never match on a primitive you didn't compile in.
From is implemented for the inner error types, which is why ? just works:
let key = DistkitRedisKey::try_from("user_123".to_string())?; // InvalidRedisKey on failure
counter.inc(&key, 1).await?; // RedisError / CounterError on failure
Lock errors
Lock-specific failures are modeled separately as LockError, surfaced through DistkitError::LockError:
pub enum LockError {
AcquireFail, // a non-blocking acquire would have to wait
Timeout { waited: Duration }, // a bounded acquire ran out of time
NotOwner, // tried to release a lock you don't hold
InvalidTtl(i64), // ttl must be positive
InvalidOwner, // owner id must not be empty
}
AcquireFail and Timeout are the two you handle routinely - they mean "the lock is busy", not "something broke". See Guard state & errors for how this interacts with lock guards.
too many results to unpack
distkit 0.7.0 and earlier versions can return this Redis error from the instance-aware counters:
Redis Error: ResponseError: user_script:16: too many results to unpack
The error occurs when the counter holds more than approximately 8,000 keys and one instance dies. Then all counter calls fail, and the counter does not recover. clear_on_instance fails in the same way when one instance holds more than approximately 8,000 keys.
To correct this, upgrade to the release that follows 0.7.0. The counter recovers on its first call after the upgrade. No manual Redis step is necessary. See the changelog.

