Struct Problem

pub struct Problem { /* private fields */ }

A RFC 7807 Problem Error.

Error Cause

This type provides methods to access the inner error cause. Although we store it, we DO NOT send it when serializing the problem, as it would leak implementation details.

Backtraces

Many implementations of the RFC add automatic backtrace to the problem. This is NOT done by this type and MUST NOT be added manually, as exposing the backtrace to the caller will expose implementation details and CAN be source of vulnerabilities.

Custom Problem Types

When an HTTP API needs to define a response that indicates an error condition, it might be appropriate to do so by defining a new problem type.

New problem type definitions MUST document:

1. a type URI (typically, with the “http” or “https” scheme),
2. a title that appropriately describes it (think short), and
3. the HTTP status code for it to be used with.

A problem type definition MAY specify additional members on the problem details object. For example, an extension might use typed links RFC 5988 to another resource that can be used by machines to resolve the problem.

Avoid defining custom problem types, preferring to use standardized HTTP status whenever possible. Custom types should only be defined if no HTTP status code can properly encode the occurred problem. As an example:

{
    "type": "https://example.com/probs/out-of-credit",
    "status": 403,
    "title": "You do not have enough credit",
    "detail": "Your current balance is 30, but that costs 50",
    "balance": 30,
    "accounts": ["/account/12345", "/account/67890"]
}

When adding a new problem type, we suggest that the type reference should also be added to the main API gateway page.

Error Instances

We currently do not track error instances (the instance field defined in the RFC). This may change in the future.

Implementations

impl Problem

Problem constructors.

pub fn custom(status: StatusCode, type: Uri) -> Self

Create a custom problem from the given type.

See the type’s documentation for more information about custom types.

pub fn from_status(status: StatusCode) -> Self

Create a new problem for the given status code.

pub fn with_title(self, title: impl Into<CowStr>) -> Self

Sets the title for this problem.

OBS: HTTP Status only problems MUST NOT have their title changed.

This method doesn’t protect against this, be sure to follow the spec.

pub fn with_detail(self, detail: impl Into<CowStr>) -> Self

Sets the detail for this problem.

pub fn with_cause<E>(self, cause: E) -> Self

where E: Error + Send + Sync + 'static,

Sets the error cause for this problem.

pub fn with_extension<E, V>(self, extension: E, value: V) -> Self

where E: Into<CowStr>, V: Serialize,

Add a new extension value for the problem.

The telemetry extension is reserved for internal use and the cause extension is reserved for future use.

Panics

Panics if field == "cause" or if the serialization of value fails.

impl Problem

Getters

pub const fn type_(&self) -> &Uri

A URI reference (RFC 3986) that identifies the problem type.

The specification encourages that, when dereferenced, it provide human-readable documentation for the problem type. When this member is not present, its value is assumed to be about:blank.

pub fn title(&self) -> &str

A short, human-readable summary of the problem type.

It SHOULD NOT change from occurrence to occurrence of the problem.

pub const fn status(&self) -> StatusCode

The HTTP status code generated by the origin server for this occurrence of the problem.

pub fn details(&self) -> &str

A human-readable explanation specific to this occurrence of the problem.

pub const fn extensions(&self) -> &Extensions

Extra members of the problem containing additional information about the specific occurrence.

pub fn extensions_mut(&mut self) -> &mut Extensions

Extra members of the problem containing additional information about the specific occurrence.

pub fn cause(&self) -> &(dyn Error + 'static)

The internal cause of this problem.

impl Problem

Error handling methods.

pub fn report(&self) -> &Report

Get the Report of this instance.

pub fn backtrace(&self) -> Backtrace

Get the backtrace for this Error.

pub fn location(&self) -> &'static Location<'static>

Location where this instance was created.

pub fn is<E>(&self) -> bool

where E: Error + Send + Sync + 'static,

Returns true if E is the type of the cause of this problem.

Useful to a failed result is caused by a specific error type.

pub fn downcast<E>(self) -> Result<E, Self>

where E: Error + Send + Sync + 'static,

Attempts to downcast the problem to a concrete type.

Errors

Returns the original problem if the underlying cause is not of the specified type.

pub fn downcast_ref<E>(&self) -> Option<&E>

where E: Error + Send + Sync + 'static,

Attempt to downcast the problem to a concrete type by reference.

pub fn isolate<E>(self) -> Result<Self, Self>

where E: Error + Send + Sync + 'static,

Attempts to isolate a specific cause to the Err variant.

This is different from a downcast as we don’t lose backtrace/source location information.

This method is useful when the user wants to handle specific errors with ?.

Errors

Returns Err when self is an E.

Trait Implementations

impl Debug for Problem

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

Formats the value using the given formatter.

impl Default for Problem

fn default() -> Problem

Returns the “default value” for a type.

impl Display for Problem

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

Formats the value using the given formatter.

impl Error for Problem

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<AssertionError> for Problem

fn from(err: AssertionError) -> Self

Converts to this type from the input type.

impl<C: CustomProblem> From<C> for Problem

fn from(custom: C) -> Self

Converts to this type from the input type.

impl Serialize for Problem

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

where S: Serializer,

Serialize this value into the given Serde serializer.