Struct Error 

pub struct Error { /* private fields */ }

A handler/framework error carrying the HTTP status to respond with.

An Error bundles everything needed to render a failed request: the StatusCode, a message (sent as the response body), an optional source error, and headers to attach to the rendered response. Return one from any handler or extractor and the pipeline turns it into a Response for you via the IntoResponse impl.

Use the constructors (Error::bad_request, Error::not_found, Error::internal, or Error::new for an arbitrary status) and chain with_source / with_response_header as needed.

use churust_core::Error;
use http::StatusCode;

let err = Error::not_found("user 42 does not exist");
assert_eq!(err.status(), StatusCode::NOT_FOUND);
assert_eq!(err.message(), "user 42 does not exist");

Implementations

impl Error

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

Create an error with an explicit status and message.

Prefer the named constructors (bad_request, not_found, internal) for the common cases; use new when you need any other status (e.g. 401 or 409).

use churust_core::Error;
use http::StatusCode;

let err = Error::new(StatusCode::CONFLICT, "already exists");
assert_eq!(err.status(), StatusCode::CONFLICT);

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

Create a 400 Bad Request error — use for malformed input such as an unparseable path parameter or invalid query string.

use churust_core::Error;
use http::StatusCode;

assert_eq!(Error::bad_request("nope").status(), StatusCode::BAD_REQUEST);

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

Create a 404 Not Found error — use when a requested resource does not exist.

use churust_core::Error;
use http::StatusCode;

assert_eq!(Error::not_found("gone").status(), StatusCode::NOT_FOUND);

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

Create a 500 Internal Server Error — use for unexpected server-side failures (e.g. a missing application-state dependency).

use churust_core::Error;
use http::StatusCode;

assert_eq!(Error::internal("boom").status(), StatusCode::INTERNAL_SERVER_ERROR);

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

Attach an underlying source error for diagnostics (exposed via std::error::Error::source). The source does not change the rendered response; it is for logging and error chaining. Returns self so it can be chained.

use churust_core::Error;
use std::error::Error as _;

let io = std::io::Error::new(std::io::ErrorKind::Other, "disk gone");
let err = Error::internal("write failed").with_source(io);
assert!(err.source().is_some());

pub fn status(&self) -> StatusCode

The HTTP status this error renders to.

use churust_core::Error;
use http::StatusCode;

assert_eq!(Error::bad_request("x").status(), StatusCode::BAD_REQUEST);

pub fn message(&self) -> &str

The human-readable message, used as the response body when rendered.

use churust_core::Error;

assert_eq!(Error::not_found("missing").message(), "missing");

pub fn with_response_header(self, name: HeaderName, value: HeaderValue) -> Self

Attach a header to the response this error renders into (e.g. WWW-Authenticate on a 401). May be called repeatedly to add several headers; returns self for chaining.

use churust_core::Error;
use http::{StatusCode, header::WWW_AUTHENTICATE, HeaderValue};

let err = Error::new(StatusCode::UNAUTHORIZED, "login required")
    .with_response_header(WWW_AUTHENTICATE, HeaderValue::from_static("Bearer"));
assert_eq!(err.response_headers().len(), 1);

pub fn response_headers(&self) -> &[(HeaderName, HeaderValue)]

The headers to apply when rendering this error to a Response. Returns an empty slice unless with_response_header was called.

use churust_core::Error;

assert!(Error::bad_request("x").response_headers().is_empty());

Trait Implementations

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<E: IntoError> From<E> for Error

fn from(e: E) -> Self

Converts to this type from the input type.

impl IntoResponse for Error

fn into_response(self) -> Response

Consume self and produce the Response to send.