Struct ErrorResponse 

pub struct ErrorResponse {
    pub status: u16,
    pub code: AppCode,
    pub message: String,
    pub details: Option<String>,
    pub retry: Option<RetryAdvice>,
    pub www_authenticate: Option<String>,
}

Public, wire-level error payload for HTTP APIs.

This type is serialized to JSON (or another transport format) and forms part of the stable wire contract between services and clients.

Fields

status: u16

HTTP status code (e.g. 404, 422, 500).

code: AppCode

Stable machine-readable error code.

message: String

Human-oriented, non-sensitive message.

details: Option<String>

Available on non-crate feature serde_json only.

Optional textual details (if serde_json is not enabled).

retry: Option<RetryAdvice>

Optional retry advice. If present, integrations set the Retry-After header.

www_authenticate: Option<String>

Optional authentication challenge. If present, integrations set the WWW-Authenticate header.

Example value: Bearer realm="api", error="invalid_token".

Implementations

impl ErrorResponse

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

Construct a new ErrorResponse with a status code, a stable AppCode, and a public message.

Errors

Returns AppError if status is not a valid HTTP status code.

pub fn status_code(&self) -> StatusCode

Convert numeric status into StatusCode.

Invalid codes default to StatusCode::INTERNAL_SERVER_ERROR.

Examples

use http::StatusCode;
use masterror::{AppCode, ErrorResponse};

let resp = ErrorResponse::new(404, AppCode::NotFound, "missing").expect("status");
assert_eq!(resp.status_code(), StatusCode::NOT_FOUND);

pub fn internal(&self) -> ErrorResponseFormatter<'_>

Formatter exposing internals for diagnostic logs.

impl ErrorResponse

pub fn with_details_text(self, details: impl Into<String>) -> Self

Available on non-crate feature serde_json only.

Attach plain-text details (available when serde_json is disabled).

impl ErrorResponse

Legacy constructor retained for migration purposes.

Deprecated: prefer ErrorResponse::new with an AppCode argument.

Examples

#[allow(deprecated)]
let response = ErrorResponse::new_legacy(404, "Not found");
assert_eq!(response.status, 404);
assert_eq!(response.message, "Not found");

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

👎Deprecated: Use new(status, code, message) instead

Construct an error response with only (status, message).

This defaults the code to AppCode::Internal. Kept temporarily to ease migration from versions prior to 0.3.0.

Examples

#[allow(deprecated)]
let response = ErrorResponse::new_legacy(500, "Internal error");
assert_eq!(response.status, 500);
assert_eq!(response.code, AppCode::Internal);
assert_eq!(response.message, "Internal error");

impl ErrorResponse

pub fn with_retry_after_secs(self, secs: u64) -> Self

Attach retry advice (number of seconds).

See with_retry_after_duration for using a Duration. When present, integrations set the Retry-After header automatically.

Examples

use masterror::{AppCode, ErrorResponse};

let resp = ErrorResponse::new(503, AppCode::Internal, "unavailable")
    .expect("status")
    .with_retry_after_secs(120);

assert_eq!(resp.retry.expect("retry").after_seconds, 120);

pub fn with_retry_after_duration(self, dur: Duration) -> Self

Attach retry advice as a Duration.

Equivalent to with_retry_after_secs. When present, integrations set the Retry-After header automatically.

Examples

use core::time::Duration;

use masterror::{AppCode, ErrorResponse};

let resp = ErrorResponse::new(503, AppCode::Internal, "retry later")
    .expect("status")
    .with_retry_after_duration(Duration::from_secs(60));
assert_eq!(resp.retry.expect("retry").after_seconds, 60);

pub fn with_www_authenticate(self, value: impl Into<String>) -> Self

Attach an authentication challenge string.

When present, integrations set the WWW-Authenticate header automatically.

Examples

use masterror::{AppCode, ErrorResponse};

let resp = ErrorResponse::new(401, AppCode::Unauthorized, "auth required")
    .expect("status")
    .with_www_authenticate("Bearer realm=\"api\"");

assert_eq!(
    resp.www_authenticate.as_deref(),
    Some("Bearer realm=\"api\"")
);

Trait Implementations

impl Clone for ErrorResponse

fn clone(&self) -> ErrorResponse

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ErrorResponse

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for ErrorResponse

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for ErrorResponse

Format ErrorResponse for logging and debugging.

Produces a concise format: "{status} {code:?}: {message}".

Examples

use masterror::{AppCode, ErrorResponse};

let resp = ErrorResponse::new(404, AppCode::NotFound, "user not found").expect("status");

let formatted = resp.to_string();
assert!(formatted.contains("404"));
assert!(formatted.contains("NOT_FOUND"));
assert!(formatted.contains("user not found"));

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

Formats the value using the given formatter.

impl From<&Error> for ErrorResponse

Convert borrowed AppError to ErrorResponse.

Clones the error’s message and metadata, leaving the original error intact. Respects MessageEditPolicy for message visibility.

Examples

use masterror::{AppError, ErrorResponse};

let err = AppError::conflict("resource exists");
let resp: ErrorResponse = (&err).into();

assert_eq!(resp.message, "resource exists");
// Original error remains intact
assert_eq!(err.message.as_deref(), Some("resource exists"));

fn from(err: &AppError) -> Self

Converts to this type from the input type.

impl From<Error> for ErrorResponse

Convert owned AppError to ErrorResponse.

Consumes the error, transferring ownership of message and metadata. Respects MessageEditPolicy for message visibility.

Examples

use masterror::{AppError, AppErrorKind, ErrorResponse};

let err = AppError::validation("invalid email");
let resp: ErrorResponse = err.into();

assert_eq!(resp.status, AppErrorKind::Validation.http_status());
assert_eq!(resp.message, "invalid email");

fn from(err: AppError) -> Self

Converts to this type from the input type.

impl Serialize for ErrorResponse

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.