Struct Error 

pub struct Error {
    pub code: Code,
    pub message: String,
    pub details: Option<Value>,
    pub trace_id: Option<String>,
    pub retryable: bool,
    pub status: u16,
    pub retry_after: Option<Duration>,
    /* private fields */
}

Structured error envelope for HTTP APIs.

Fields

code: Code

Machine-readable error code.

message: String

Human-readable error message.

details: Option<Value>

Optional structured details (e.g., field-level validation errors).

trace_id: Option<String>

Optional trace ID for distributed tracing.

retryable: bool

Whether the client should retry this request.

status: u16

HTTP status code.

retry_after: Option<Duration>

Optional retry-after duration for rate limiting.

Implementations

impl Error

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

Creates a new error with the given code, status, and message.

pub fn newf(code: Code, status: u16, message: impl Into<String>) -> Self

Creates a new error with a formatted message.

This is a semantic alias for new() that signals the message is typically constructed with format!().

Example

use error_envelope::{Error, Code};
let user_id = 123;
let err = Error::newf(Code::NotFound, 404, format!("user {} not found", user_id));

pub fn wrap( code: Code, status: u16, message: impl Into<String>, cause: impl Error, ) -> Self

Creates a new error that wraps an underlying cause.

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

Adds structured details to the error.

pub fn with_trace_id(self, trace_id: impl Into<String>) -> Self

Adds a trace ID for distributed tracing.

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

Sets whether the error is retryable.

pub fn with_status(self, status: u16) -> Self

Overrides the HTTP status code.

pub fn with_retry_after(self, duration: Duration) -> Self

Sets the retry-after duration for rate-limited responses.

pub fn with_cause_message(self, cause: impl Error) -> Self

Attaches a cause message from an underlying error.

Useful when mapping domain errors (e.g., thiserror) to HTTP errors while preserving the underlying error message for debugging.

Example

use error_envelope::{Error, Code};

#[derive(Debug)]
struct DatabaseError;
impl std::fmt::Display for DatabaseError {
    fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
        write!(f, "connection timeout")
    }
}
impl std::error::Error for DatabaseError {}

let db_err = DatabaseError;
let err = Error::new(Code::Internal, 500, "Database failure")
    .with_cause_message(db_err);

pub fn cause(&self) -> Option<&str>

Returns the cause message if available.

pub fn status(&self) -> u16

Returns the HTTP status code.

impl Error

Helper constructors for common error types.

pub fn internal(message: impl Into<String>) -> Self

Creates an internal server error (500).

pub fn bad_request(message: impl Into<String>) -> Self

Creates a bad request error (400).

pub fn validation(message: impl Into<String>) -> Self

Creates a validation error (400).

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

Creates an unauthorized error (401).

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

Creates a forbidden error (403).

pub fn not_found(message: impl Into<String>) -> Self

Creates a not found error (404).

pub fn method_not_allowed(message: impl Into<String>) -> Self

Creates a method not allowed error (405).

pub fn request_timeout(message: impl Into<String>) -> Self

Creates a request timeout error (408).

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

Creates a conflict error (409).

pub fn gone(message: impl Into<String>) -> Self

Creates a gone error (410).

pub fn payload_too_large(message: impl Into<String>) -> Self

Creates a payload too large error (413).

pub fn unprocessable_entity(message: impl Into<String>) -> Self

Creates an unprocessable entity error (422).

pub fn rate_limited(message: impl Into<String>) -> Self

Creates a rate limited error (429).

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

Creates a timeout error (504).

pub fn unavailable(message: impl Into<String>) -> Self

Creates an unavailable error (503).

pub fn downstream(service: impl Into<String>, cause: impl Error) -> Self

Creates a downstream error (502).

pub fn downstream_timeout(service: impl Into<String>, cause: impl Error) -> Self

Creates a downstream timeout error (504).

Trait Implementations

impl Clone for Error

fn clone(&self) -> Error

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Error

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

Formats the value using the given formatter.

impl Display for Error

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

Formats the value using the given formatter.

impl Error for Error

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 Serialize for Error

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

where S: Serializer,

Serialize this value into the given Serde serializer.