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>) -> AppError

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

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

Attach an underlying cause to this error.

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

Add a single key-value detail entry.

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

Merge a map of detail entries into this error.

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

Override whether this error is considered retryable.

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

Create a ServiceUnavailable error for the named service.

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

Create a ConnectionFailed error for the named service.

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

Create a Timeout error for the named operation.

pub fn rate_limited() -> AppError

Create a RateLimited error.

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

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

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

Create an AlreadyExists error for the named resource.

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

Create a Conflict error with the given reason.

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

Create an InvalidInput error for the named field.

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

Create a MissingField error for the named required field.

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

Create an InvalidFormat error for the named field.

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

Create an Unauthorized error with the given reason.

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

Create a Forbidden error with the given reason.

pub fn token_expired() -> AppError

Create a TokenExpired error.

pub fn invalid_token() -> AppError

Create an InvalidToken error.

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

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) -> AppError

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, ) -> AppError

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>) -> AppError

Create a Cancelled error for the named operation.

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

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 hint(self, hint: impl Into<String>) -> AppError

Append a trailing hint after the existing error message.

The counterpart to context: where context prepends call-site context, hint appends advisory guidance (for example a “did you mean …?” suggestion) as a new sentence, preserving the code, cause, structured details, and retryability of the original error.

An empty or whitespace-only hint is a no-op, so an optional or derived suggestion can be threaded through without a conditional at the call site. The hint is trimmed of surrounding whitespace and appended onto the existing message (separated by a single space when the message is non-empty); the caller supplies any punctuation within the hint itself.

Examples

let err = AppError::invalid_input("task", "no such task 'buld'")
    .hint("Did you mean 'build'?");
assert_eq!(
    err.message(),
    "invalid task: no such task 'buld' Did you mean 'build'?"
);

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 + Sync + Send + 'static)>

Underlying source error, if one was attached.

Trait Implementations

impl Debug for AppError

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

Formats the value using the given formatter.

impl Display for AppError

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

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<ApiError> for AppError

fn from(e: ApiError) -> AppError

Converts to this type from the input type.

impl From<Error> for AppError

fn from(e: Error) -> AppError

Converts to this type from the input type.

impl From<Error> for AppError

fn from(e: Error) -> AppError

Converts to this type from the input type.

impl From<Error> for AppError

fn from(e: Error) -> AppError

Converts to this type from the input type.

impl From<GitError> for AppError

fn from(error: GitError) -> AppError

Converts to this type from the input type.

impl From<InferenceError> for AppError

fn from(value: InferenceError) -> AppError

Converts to this type from the input type.

impl From<SkillError> for AppError

fn from(value: SkillError) -> AppError

Converts to this type from the input type.

impl From<Utf8Error> for AppError

fn from(e: Utf8Error) -> AppError

Converts to this type from the input type.

impl Serialize for AppError

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

where S: Serializer,

Serialize this value into the given Serde serializer.