Attribute Macro error_handler 

#[error_handler]

Define an error handler.

Error handlers are invoked whenever an error occurs during request processing, allowing you to transform errors into HTTP responses.

Example

use pavex::error_handler;
use pavex::Response;

#[error_handler]
pub fn handle_auth_error(e: &AuthError) -> Response {
    // Transform the error into an HTTP response
    Response::unauthorized()
}

Guide

Check out the "Error handling" section of Pavex’s guide for a thorough introduction to error handling in Pavex applications.

Registration

You can register an error handler with your application in two ways:

• Use Blueprint::error_handler to register a single error handler
• Use Blueprint::import to import multiple error handlers in bulk

The #[error_handler] macro generates a constant that you can use to refer to the error handler when invoking Blueprint::error_handler.

Arguments

The sections below provide an exhaustive list of all the arguments and helper attributes supported by the error_handler macro:

Name	Kind	Required
px(error_ref)	Helper attribute	Sometimes
id	Argument	No
default	Argument	No

error_ref

One of the input parameters for an error handler must be a reference to the error type that’s being handled.

Pavex infers the error type automatically if the error handler has a single input parameter.
If there are multiple input parameters, you must annotate the error reference with #[px(error_ref)].

Example: single input parameter

use pavex::methods;
use pavex::Response;

pub struct AuthError { /* */ };

#[methods]
impl AuthError {
    #[error_handler]
    // A single input parameter, no need for additional annotations
    // Pavex will infer that `&self` is the error reference
    pub fn to_response(&self) -> Response {
        // [...]
    }
}

Example: multiple input parameters

use pavex::methods;
use pavex::Response;

pub struct AuthError { /* */ };

#[methods]
impl AuthError {
    #[error_handler]
    pub fn to_response(
        #[px(error_ref)] &self,
        // 👆
        // Multiple input parameters, you must mark the error reference
        organization_id: OrgId
    ) -> Response {
        // [...]
    }
}

id

When using Blueprint::error_handler, Pavex generates a constant named after your function (converted to UPPER_SNAKE_CASE) that you can use to refer to the error handler when invoking Blueprint::error_handler.

The id argument allows you to customize the name of the generated constant.

Example

Using the default identifier:

use pavex::{error_handler, Blueprint};
use pavex::Response;

#[error_handler]
pub fn handle_auth_error(e: &AuthError) -> Response {
    // [...]
}

let mut bp = Blueprint::new();
bp.error_handler(HANDLE_AUTH_ERROR);

Using a custom identifier:

use pavex::{error_handler, Blueprint};
use pavex::Response;

#[error_handler(id = "AUTH_HANDLER")]
//              👆 Custom identifier
pub fn handle_auth_error(e: &AuthError) -> Response {
    // [...]
}

let mut bp = Blueprint::new();
bp.error_handler(AUTH_HANDLER);

default

The default argument determines whether this error handler should be used as the default handler for the error type whenever an error of the matching type is emitted.

By default, error handlers are considered the default handler for their error type (default = true).

Example

use pavex::{error_handler, get, Blueprint};
use pavex::Response;

#[error_handler]
// This is the default handler for `AuthError`s
pub fn handle_auth_error(e: &AuthError) -> Response {
}

#[error_handler(default = false)]
//              👆 Not the default handler
pub fn handle_auth_error_admin(e: &AuthError) -> Response {
}

#[get(path = "/admin")]
pub fn admin_route() -> Result<Response, AuthError> {
    // Admin-specific logic
}

let mut bp = Blueprint::new();
// Register the default error handler
bp.error_handler(HANDLE_AUTH_ERROR);
// Specify a different error handler for the admin route
bp.route(ADMIN_ROUTE).error_handler(HANDLE_AUTH_ERROR_ADMIN);