Struct AppError 

pub struct AppError { /* private fields */ }

Application-level structured error.

Carries a machine-readable ErrorCode, a human-readable message, optional key→value details for rich error responses, and an optional cause chain compatible with std::error::Error.

Fields are private to preserve the error’s invariants. http_status is fully determined by code and can never drift from it. retryable is seeded from code’s default but may be intentionally overridden via the AppError::retryable builder; read access is via the getter methods and mutation via the builder methods (with_*, retryable, context).

details deliberately uses serde_json::Value: it models RFC 9457 problem-detail extension members, which are by definition arbitrary JSON and cannot be given a closed type without losing that openness.

Implementations

impl AppError

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

Create a new AppError from code and a human-readable message.

pub fn with_cause(self, cause: impl Error + Send + Sync + 'static) -> Self

Attach an underlying cause to this error.

pub fn with_detail( self, key: impl Into<String>, value: impl Into<Value>, ) -> Self

Add a single key-value detail entry.

pub fn with_details(self, details: HashMap<String, Value>) -> Self

Merge a map of detail entries into this error.

pub fn retryable(self, r: bool) -> Self

Override whether this error is considered retryable.

pub fn service_unavailable(service: impl Into<String>) -> Self

Create a ServiceUnavailable error for the named service.

pub fn connection_failed(service: impl Into<String>) -> Self

Create a ConnectionFailed error for the named service.

pub fn timeout(operation: impl Into<String>) -> Self

Create a Timeout error for the named operation.

pub fn rate_limited() -> Self

Create a RateLimited error.

pub fn not_found(resource: impl Into<String>, id: Option<&str>) -> Self

Create a NotFound error for resource, optionally including an id.

pub fn already_exists(resource: impl Into<String>) -> Self

Create an AlreadyExists error for the named resource.

pub fn conflict(reason: impl Into<String>) -> Self

Create a Conflict error with the given reason.

pub fn invalid_input( field: impl Into<String>, reason: impl Into<String>, ) -> Self

Create an InvalidInput error for the named field.

pub fn missing_field(field: impl Into<String>) -> Self

Create a MissingField error for the named required field.

pub fn invalid_format( field: impl Into<String>, expected: impl Into<String>, ) -> Self

Create an InvalidFormat error for the named field.

pub fn unauthorized(reason: impl Into<String>) -> Self

Create an Unauthorized error with the given reason.

pub fn forbidden(reason: impl Into<String>) -> Self

Create a Forbidden error with the given reason.

pub fn token_expired() -> Self

Create a TokenExpired error.

pub fn invalid_token() -> Self

Create an InvalidToken error.

pub fn internal(cause: impl Error + Send + Sync + 'static) -> Self

Wrap an arbitrary error as an Internal application error.

The cause is stored internally for logging but is NOT included in the serialized response — callers receive a generic “internal server error” message.

pub fn database_error(cause: impl Error + Send + Sync + 'static) -> Self

Wrap a database error.

The cause is stored internally for logging but is NOT included in the serialized response — callers receive a generic “database error” message.

pub fn external_service( service: impl Into<String>, cause: impl Error + Send + Sync + 'static, ) -> Self

Wrap an external service error, naming the dependency.

The cause is stored internally for logging but is NOT included in the serialized response — callers receive a generic message naming only the service.

pub fn cancelled(operation: impl Into<String>) -> Self

Create a Cancelled error for the named operation.

pub fn context(self, msg: impl Into<String>) -> Self

Add human-readable context to this error.

Prepends msg to the existing error message so call-site context is preserved in logs and error responses without losing the original cause.

Examples

let err = AppError::new(ErrorCode::NotFound, "user not found")
    .context("load profile");
assert_eq!(err.message(), "load profile: user not found");

pub fn is_retryable(&self) -> bool

Returns true if the operation that produced this error is safe to retry.

pub fn is_not_found(&self) -> bool

Returns true if this error indicates a missing resource.

pub fn is_unauthorized(&self) -> bool

Returns true if this error is an authentication/authorisation failure.

pub const fn code(&self) -> ErrorCode

Machine-readable error classification.

pub fn message(&self) -> &str

Human-readable error message.

pub const fn http_status(&self) -> StatusCode

Canonical HTTP status code for this error.

pub fn details(&self) -> &HashMap<String, Value>

Additional structured error details.

pub fn cause(&self) -> Option<&(dyn Error + Send + Sync + 'static)>

Underlying source error, if one was attached.

Trait Implementations

impl Debug for AppError

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

Formats the value using the given formatter.

impl Display for AppError

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

Formats the value using the given formatter.

impl Error for AppError

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<&AppError> for StatusCode

fn from(e: &AppError) -> Self

Converts to this type from the input type.

impl From<&AppError> for ProblemDetail

fn from(err: &AppError) -> Self

Converts to this type from the input type.

impl From<AppError> for ProblemDetail

fn from(err: AppError) -> Self

Converts to this type from the input type.

impl From<Error> for AppError

fn from(e: Error) -> Self

Converts to this type from the input type.

impl From<Error> for AppError

fn from(e: Error) -> Self

Converts to this type from the input type.

impl From<Error> for AppError

fn from(e: Error) -> Self

Converts to this type from the input type.

impl From<Utf8Error> for AppError

fn from(e: Utf8Error) -> Self

Converts to this type from the input type.

impl Serialize for AppError

fn serialize<S: Serializer>(&self, ser: S) -> Result<S::Ok, S::Error>

Serialize this value into the given Serde serializer.