Error Handling

This is the day-to-day patterns guide for writing fallible code in Suprnova handlers, services, and middleware. For the underlying model - the conversion contract, the panic boundary, the 5xx sanitisation rule, the development error page, observability hooks - read Error Model. This chapter shows what to actually type.

The shape to remember:

• Handlers return Response = Result<HttpResponse, HttpResponse>.
• ? performs one direct From<E> conversion into the handler's error type; Rust does not chain DbErr -> FrameworkError -> HttpResponse. In a Response handler, convert a SeaORM error explicitly. Code that already returns Result<_, FrameworkError> may use .await? directly.
• Three free helpers (abort_with, abort_if, abort_unless) let you short-circuit at a status code without naming an error type.

use sea_orm::EntityTrait;
use suprnova::{DB, FrameworkError, Request, Response, json_response};

pub async fn show(req: Request) -> Response {
    let id: i64 = req.param("id")?.parse()
        .map_err(|_| FrameworkError::param_parse("id", "i64"))?;
    let user = users::Entity::find_by_id(id)
        .one(&*DB::get()?)
        .await
        .map_err(FrameworkError::from)?
        .ok_or_else(|| FrameworkError::not_found("User"))?;
    json_response!({ "user": user })
}

The rest of the chapter is the catalogue of error producers - what to construct, what status it returns, what shape the client sees.

? is the conversion

Every ? in a handler body performs one direct From<E> for HttpResponse conversion. The framework provides direct conversions for its handler-facing error types, but Rust does not chain multiple From implementations. Convert an intermediate error explicitly when it has no direct conversion to HttpResponse.

use suprnova::{DB, FrameworkError, Request, Response, json_response};
use sea_orm::EntityTrait;

pub async fn show(req: Request) -> Response {
    let id: i64 = req.param("id")?.parse()
        .map_err(|_| FrameworkError::param_parse("id", "i64"))?;

    let user = users::Entity::find_by_id(id)
        .one(&*DB::get()?)
        .await
        .map_err(FrameworkError::from)?
        .ok_or_else(|| FrameworkError::not_found("User"))?;

    json_response!({ "user": user })
}

Four conversions happen in that snippet:

1. req.param("id")? directly converts ParamError to an HttpResponse (400).
2. The parse error is explicitly mapped to FrameworkError::ParamError, which ? then directly converts to an HttpResponse (400).
3. The SeaORM error is explicitly mapped from DbErr to FrameworkError::Database; ? then directly converts that FrameworkError to an HttpResponse (500, sanitised on the wire).
4. .ok_or_else(...)? turns None into FrameworkError::ModelNotFound, which converts to an HttpResponse (404).

Each ? uses one direct conversion. Code that returns Result<_, FrameworkError> instead of Response may use .await? on the SeaORM call because DbErr converts directly to FrameworkError.

Every one of those conversions ends in the framework's JSON error body - { "message": …, "request_id": … } at the matching status. That is the right answer for an API client and the wrong one for an Inertia visit, which needs a page. Name an error page and an Inertia app renders these errors as a real page while API clients keep the JSON unchanged. With debug mode on, a 5xx reaches a browser or an Inertia visit as the development error page instead.

AppError - inline domain errors

Use AppError for one-off errors that don't deserve a dedicated type. The constructors map onto Laravel's abort($status, $msg) shape:

AppError has a From into FrameworkError, so ? works with no ceremony:

use suprnova::{AppError, Request, Response, json_response};

pub async fn transfer(req: Request) -> Response {
    let amount: i64 = req.param("amount")?.parse()
        .map_err(|_| AppError::bad_request("amount must be a number"))?;

    if amount <= 0 {
        return Err(AppError::unprocessable("amount must be positive").into());
    }

    if amount > balance() {
        return Err(AppError::forbidden("amount exceeds daily limit").into());
    }

    json_response!({ "transferred": amount })
}

Note the asymmetry: AppError::unauthorized is 401 (missing authentication credentials), while FrameworkError::Unauthorized is 403 (policy denied an authenticated user). They mean different things; pick the one that matches the failure.

FrameworkError - the canonical enum

Internal extractors, the container, route binding, validation, the database layer, and storage all produce FrameworkError. You usually construct one through a convenience constructor and let ? route it.

use suprnova::FrameworkError;

FrameworkError::not_found("User");                    // 404
FrameworkError::bad_request("Bad input");             // 400
FrameworkError::param("user_id");                     // 400
FrameworkError::param_parse("user_id", "i64");        // 400
FrameworkError::validation("email", "required");      // 422
FrameworkError::domain("Conflict", 409);              // 409 (any code)
FrameworkError::internal("disk full");                // 500
FrameworkError::database("timeout");                  // 500
FrameworkError::service_not_found::<MyService>();     // 500
FrameworkError::model_not_found("Post");              // 404

The full variant set, with implications for the response shape, is in Error Model. The constructors above cover every common case; you reach for the variants directly only when matching on an error you received.

Automatic conversions

FrameworkError already speaks the dialects your dependencies emit. Both of these ?s convert automatically:

use suprnova::{DB, FrameworkError};
use sea_orm::ActiveModelTrait;

pub async fn create_user(new_user: users::ActiveModel)
    -> Result<users::Model, FrameworkError>
{
    // DB::get returns Result<_, FrameworkError>.
    // .insert returns Result<_, DbErr>, with From<DbErr> for FrameworkError.
    let user = new_user.insert(&*DB::get()?).await?;
    Ok(user)
}

The framework also implements From<opendal::Error> for storage operations and From<ParamError> for path-parameter extraction.

Re-raising with context

When you want to annotate where an error came from without losing the status code, use .context():

db.insert(user).await
    .map_err(FrameworkError::from)
    .map_err(|e| e.context("creating new user"))?;

The message becomes "creating new user: <original>". Structured variants (Validation, ValidationError, ModelNotFound, ParamParse, PrecognitionFailure, PrecognitionSuccess, Unauthorized, UnsupportedMediaType, AlreadyReported, RateLimited, Timeout, External) keep their variant so the response renderer still emits the right shape (and, for External, so the wrapped source survives); flat message-carrying variants (Internal, Database, Domain) flatten into a Domain with the prefixed message and the original status preserved.

Turning duplicate-key errors into 422

The Unique validation rule runs a SELECT COUNT(*) before the write, so it's advisory - two concurrent requests can both pass and then both attempt the insert. The losing request gets a database unique-constraint violation, which would otherwise leak as a 500. from_unique_violation translates it into the same 422 the advisory rule would have produced:

use suprnova::FrameworkError;

let user = new_user.insert(db).await.map_err(|e| {
    FrameworkError::from_unique_violation(
        "email",
        "That email address is already registered.",
        e,
    )
})?;

If the underlying DbErr isn't a unique-constraint violation it passes through unchanged as a 500-class Database error. Backend coverage is whatever SeaORM's DbErr::sql_err recognises - Postgres, MySQL/MariaDB, and SQLite all map their duplicate-key errors through.

Wrapping a foreign error

Every other variant stringifies what it wraps. from_external_with keeps the original error reachable, so logs can render the whole chain and code can still ask what actually failed:

use suprnova::FrameworkError;

let row = sqlx_like_query()
    .await
    .map_err(|e| FrameworkError::from_external_with("verify query failed", e))?;

from_external(e) is the same thing with the error's own Display as the message. Both map to HTTP 500.

To inspect the original, use external_source() rather than source():

if let Some(src) = err.external_source() {
    if let Some(db) = src.downcast_ref::<sea_orm::DbErr>() {
        // decide whether this is worth retrying
    }
}

std::error::Error::source() hands back the shared Arc handle, not the wrapped error, so downcasting through it returns None. external_source() dereferences the handle first.

The framework renders the full chain into the 5xx log line. When APP_DEBUG=true, it also shows the chain on the development error page for a browser or an Inertia visit, and in the debug_message field of the JSON body for every other client, so a wrapped error's text is never lost.

Preserving rate-limit hints

When a downstream service throttles you and supplies a Retry-After hint, wrapping the failure in internal(...) melts the duration into prose. rate_limited keeps it structured:

use std::time::Duration;
use suprnova::FrameworkError;

let err = FrameworkError::rate_limited(
    Some(Duration::from_secs(30)),
    "push provider rejected the batch",
);

assert_eq!(err.retry_after(), Some(Duration::from_secs(30)));
assert_eq!(err.status_code(), 429);

Queue retry policies, jitter scheduling, and the HTTP Retry-After response header all read the hint back through retry_after(), which returns None for every other variant and for throttles that came without one. .context(...) preserves the variant, so adding operation context does not strip the duration.

Telling a passed deadline from a failure

FrameworkError::Timeout means a deadline passed before the awaited work finished. FrameworkError::timeout(elapsed, message) builds one, and is_timeout() asks for it. It renders as 504 Gateway Timeout, and the client sees the generic 5xx message. The workflow wait returns it, so a handler can tell a workflow that is still running from a failure:

use std::time::Duration;
use suprnova::FrameworkError;

let err = FrameworkError::timeout(Duration::from_secs(30), "waiting for the export");

assert!(err.is_timeout());
assert_eq!(err.status_code(), 504);

See Error Model and Workflows.

Custom domain errors

Three tiers, depending on how reusable the error needs to be.

#[domain_error] for the typed case

Most reusable errors want a name, a fixed status, and a fixed message template - no per-call message. The #[domain_error] attribute macro generates Display, std::error::Error, HttpError, and From for FrameworkError in one shot:

use suprnova::domain_error;

#[domain_error(status = 404, message = "User not found")]
pub struct UserNotFound;

#[domain_error(status = 402, message = "Insufficient funds")]
pub struct InsufficientFunds {
    pub available: i64,
    pub requested: i64,
}

Use them at the call site with ?:

use crate::errors::user_not_found::UserNotFound;

pub async fn show(req: Request) -> Response {
    let id: i64 = req.param("id")?.parse()
        .map_err(|_| FrameworkError::param_parse("id", "i64"))?;

    let user = find_user(id).await
        .ok_or_else(|| FrameworkError::from(UserNotFound))?;

    json_response!({ "user": user })
}

The macro rejects malformed attributes loudly at compile time - overflowed status codes (status = 70_000), wrong literal types (message = 42), unknown keys - so you can't silently get the wrong status because of a typo.

Scaffold one with the CLI

suprnova make:error UserNotFound

Writes src/errors/user_not_found.rs with a default status = 500 and an inferred sentence-cased message, and updates src/errors/mod.rs to re-export it. Edit the status and message to taste.

HttpError for the hand-rolled case

When a domain error needs runtime state in the message (e.g. the IDs involved in the failure), implement HttpError directly. The trait has two methods with sensible defaults:

use suprnova::HttpError;

#[derive(Debug)]
pub struct InsufficientFunds {
    pub available: i64,
    pub requested: i64,
}

impl std::fmt::Display for InsufficientFunds {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "Insufficient funds: have {}, need {}",
            self.available, self.requested)
    }
}

impl std::error::Error for InsufficientFunds {}

impl HttpError for InsufficientFunds {
    fn status_code(&self) -> u16 { 402 }
    fn error_message(&self) -> String {
        format!("Need {} units, only {} available.",
            self.requested, self.available)
    }
}

To bridge a hand-rolled HttpError into ?, call FrameworkError::from_http_error. A blanket From<T: HttpError> for FrameworkError would conflict with the existing From<AppError> impl, so the bridge is an explicit constructor:

account.withdraw(amount)
    .map_err(FrameworkError::from_http_error)?;

Error enums for one module's failures

When a service has several related failures, group them in an enum and write one From for the whole enum:

use suprnova::FrameworkError;
use thiserror::Error;

#[derive(Debug, Error)]
pub enum OrderError {
    #[error("Order {0} not found")]
    NotFound(i64),

    #[error("Insufficient stock for product {product_id}")]
    InsufficientStock { product_id: i64 },

    #[error("Payment failed: {0}")]
    PaymentFailed(String),

    #[error("Order already shipped")]
    AlreadyShipped,
}

impl From<OrderError> for FrameworkError {
    fn from(err: OrderError) -> Self {
        let status = match &err {
            OrderError::NotFound(_) => 404,
            OrderError::InsufficientStock { .. } => 422,
            OrderError::PaymentFailed(_) => 402,
            OrderError::AlreadyShipped => 409,
        };
        FrameworkError::Domain {
            message: err.to_string(),
            status_code: status,
        }
    }
}

Once the From exists, the enum threads through ? the same as any other error type.

abort_with / abort_if / abort_unless

Three helpers short-circuit a handler at a status. They mirror Laravel's abort / abort_if / abort_unless. (The free function is exported as abort_with rather than abort to keep the latter available as a method name on user types.)

use suprnova::{abort_if, abort_unless, abort_with, Request, Response, json_response};

pub async fn show(req: Request) -> Response {
    abort_unless(Auth::user().await?.is_some(), 401, "must be logged in")?;
    abort_if(req.param("id")? == "0", 404, "User not found")?;
    abort_with(503, "scheduled maintenance")?;

    json_response!({ "ok": true })
}

Each returns Result<(), FrameworkError>, so ? does the work. The underlying error is FrameworkError::Domain { message, status_code }, which renders through the same body shape as every other error. Out-of-range status codes are coerced to 500 by the response renderer; you don't need to defend against bad input at the call site.

ValidationErrors - the Laravel-shaped error bag

When validation fails - at #[derive(Validate)] time or in an after_validation body - the framework emits the JSON shape Laravel and Inertia front-ends expect:

{
    "message": "The given data was invalid.",
    "errors": {
        "email": ["The email field must be a valid email address."],
        "password": ["The password field must be at least 8 characters."]
    },
    "request_id": "8f9e1a2b-c3d4-..."
}

Most of the time you don't construct this directly - #[derive(Validate)] runs and the framework converts validator::ValidationErrors for you. When you need to add errors imperatively (cross-field rules, async uniqueness checks that complement Unique), build a ValidationErrors and return it:

use suprnova::{FrameworkError, ValidationErrors};

pub async fn after_validation(payload: &Signup) -> Result<(), FrameworkError> {
    let mut errs = ValidationErrors::new();

    if payload.email.ends_with("@example.com") {
        errs.add("email", "example.com addresses are not allowed");
    }
    if payload.password == payload.email {
        errs.add("password", "password must not match email");
    }

    errs.into_result().map_err(FrameworkError::Validation)
}

add_to_bag scopes a field under a named bag (Laravel's withErrors($errors, 'profile') shape) by prepending the bag with a . separator. Useful when one response carries errors from multiple sub-forms that can't share a flat namespace:

let mut errs = ValidationErrors::new();
errs.add_to_bag("profile", "bio", "must be under 280 characters");
errs.add_to_bag("billing", "card", "expired");
// errors map: { "profile.bio": [...], "billing.card": [...] }

from_validator(ve) converts a validator::ValidationErrors; retain_fields(&keep) returns a copy containing only the listed entries (used by Precognition's Precognition-Validate-Only header internally).

Hooking observability with ErrorOccurred

Every 5xx response fires an ErrorOccurred event - including the ones synthesised from panics. Listen the same way you listen for any event:

use std::sync::Arc;
use suprnova::{ErrorOccurred, EventFacade, FrameworkError, Listener};

pub struct SentryReporter;

#[suprnova::async_trait]
impl Listener<ErrorOccurred> for SentryReporter {
    async fn handle(&self, evt: &ErrorOccurred) -> Result<(), FrameworkError> {
        sentry::capture_message(&evt.error_message, sentry::Level::Error);
        Ok(())
    }
}

// In bootstrap.rs:
// `listen` infers both generics from the listener type. It returns
// `()` (the registration cannot fail), so no `?` and no Result.
EventFacade::listen::<ErrorOccurred, SentryReporter>(Arc::new(SentryReporter)).await;

The event carries the raw error message (the wire body is still sanitised - see Error Model), the status, and the correlatable request id. To run code for failed queue jobs and console commands too, register a callback with Exceptions::reportable.

Report errors with Exceptions

Exceptions is the place every error the framework does not answer itself goes through, as Laravel's exception handler is. These errors are reported:

• Every FrameworkError that becomes a 5xx response. ErrorOccurred still fires after it.
• Every error behind a 5xx response the framework builds itself: a session the store cannot write, a Live or WebSocket request the framework cannot prepare or answer, a rate limiter or render cache that fails closed, a readiness probe whose database check fails, and a payment webhook that fails.
• Every failed attempt of a queued job: a handler that returns Err or panics, an attempt that runs past its timeout, and an error FailOnException fails the job for.
• Every error a console command returns, and every failure of the boot before it runs: a bootstrap that panics, such as one whose DB::init().await.expect(..) finds no database, a log channel nothing defines, or a service the container cannot build. This covers the console binary's commands and the application binary's (queue:work, schedule:interrupt, down and the others). The callbacks your bootstrap registered before it failed see the failure.
• Every error you pass to Exceptions::report.

A report runs your callbacks in the order you registered them. Then it writes the framework error log line, with the status, the full source chain, and the request id when there is one. When the framework builds a 5xx for a failure it has already logged, such as a rate limiter that fails closed, you get that line, with its own fields, in place of the framework error line, so each failure is logged once. A callback with stop() does not hold back that line.

Register callbacks once, in bootstrap.rs. The parameter type of the closure decides which errors it receives:

use suprnova::{Exceptions, FrameworkError};

#[derive(Debug)]
pub struct PaymentDeclined(pub String);

impl std::fmt::Display for PaymentDeclined {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "payment declined: {}", self.0)
    }
}

impl std::error::Error for PaymentDeclined {}

pub fn register_reporting() {
    // Every reported error.
    Exceptions::reportable(|error: &FrameworkError| {
        eprintln!("reported: {error}");
    });

    // Only errors that wrap a `PaymentDeclined`. `stop()` keeps the
    // callbacks after this one and the default log line from running
    // for those errors.
    Exceptions::reportable(|error: &PaymentDeclined| {
        eprintln!("billing alert: {error}");
    })
    .stop();
}

A callback that takes &FrameworkError receives every error. A callback that takes another error type E receives an error whose wrapped source is an E: the error you passed to FrameworkError::from_external or from_external_with. Only that wrapped error is compared, not the errors in its own source() chain. To act on a deeper cause, take &FrameworkError and walk std::error::Error::source yourself.

To report an error your code handles, and still have it recorded, pass it to Exceptions::report:

use suprnova::{Exceptions, FrameworkError};

fn read_settings() -> String {
    match std::fs::read_to_string("storage/settings.json") {
        Ok(settings) => settings,
        Err(e) => {
            Exceptions::report(&FrameworkError::from_external_with(
                "reading the settings failed; using the defaults",
                e,
            ));
            String::from("{}")
        }
    }
}

Exceptions::dont_retry::<E>() and Exceptions::dont_retry_when name the errors that end a queued job's retries. See Queue.

Why Suprnova diverges

• A Laravel callback that returns false also stops reporting. A Suprnova callback returns nothing, so stop() is the only way to stop.
• An exception thrown from a Laravel callback ends the report. A Suprnova callback that panics is logged, and the report goes on to the next callback and the log line. A broken reporter cannot take a queue worker down.
• Exceptions::report takes a FrameworkError. Wrap a foreign error with FrameworkError::from_external first.

See a failure in the browser

With debug mode on, a route that fails with a 5xx shows the development error page in a browser instead of a JSON body. Debug mode is on when APP_DEBUG=true, and when APP_DEBUG is unset in the local, development, or testing environment.

use suprnova::{FrameworkError, HttpResponse, Request, Response};

pub async fn post_invoice(_req: Request) -> Response {
    write_ledger()?;
    HttpResponse::text("posted").ok()
}

fn write_ledger() -> Result<(), FrameworkError> {
    std::fs::write("storage/ledger.log", b"invoice 42\n")
        .map_err(|e| FrameworkError::from_external_with("writing the ledger failed", e))
}

When the write fails, a browser that opens the route gets a 500 page that shows the following:

• The message writing the ledger failed, and the I/O error it wraps.
• The line in write_ledger that called from_external_with, and the stack frames of your code that led there. The frames of the framework, the async runtime, dependencies and the standard library are collapsed behind a count. You see the source line and a few lines around each application frame when its file is readable. You also see a separate trace for each source error that recorded frames.
• The request's method, path, query, headers, route pattern, and request id. Credentials and secret-named values are redacted, including the secret parameters of a URL in a header such as Referer.

An Inertia visit gets the same page, in place of your Inertia error page. curl, and every other client whose Accept header does not list text/html, still gets {"message": "Internal Server Error", "request_id": "...", "debug_message": "..."}. With debug off, you receive a minimal HTML error view for a 5xx when your request accepts text/html and is not an Inertia visit. You see the status with no error detail or frames. Your Inertia visits keep your app error page, and your JSON requests keep their JSON body. The rules are in Error Model.

Why Suprnova diverges

Laravel's exception page also shows the request body and runs a script for its "copy as Markdown" button. Suprnova's page does neither. A request body can hold the passwords and tokens the page redacts everywhere else, and a page that runs no script and loads nothing still renders when your frontend build is what broke.

Patterns you'll write a lot

Parse a path parameter as a typed value

let id: i64 = req.param("id")?.parse()
    .map_err(|_| FrameworkError::param_parse("id", "i64"))?;

ParamError already converts to 400; param_parse is the parse-failure equivalent and renders the same shape.

Look up by ID, 404 on absent

let user = users::Entity::find_by_id(id)
    .one(&*DB::get()?)
    .await
    .map_err(FrameworkError::from)?
    .ok_or_else(|| FrameworkError::not_found("User"))?;

map_err(FrameworkError::from)? bridges the SeaORM DbErr through From<DbErr> for FrameworkError and then through From<FrameworkError> for HttpResponse. Rust does not auto-chain From impls across two hops, so the explicit .map_err is required.

Or, with the Eloquent layer (which already wraps SeaORM and returns Result<_, FrameworkError> directly):

use suprnova::Model;

let user = User::find_or_fail(id).await?;

find_or_fail is find(id).ok_or(ModelNotFound) packaged up.

Authorize an action

let user = Auth::user().await?
    .ok_or_else(|| AppError::unauthorized("login required"))?;
abort_unless(post.owner_id == user.id() || user.is_admin(), 403,
    "you don't own this post")?;

abort_unless returns Result<(), FrameworkError>; the ? collapses it back into your handler's error arm.

Service returning typed errors

use suprnova::{App, FrameworkError, injectable};

#[injectable]
pub struct UserService;

impl UserService {
    pub async fn find_by_email(&self, email: &str)
        -> Result<users::Model, FrameworkError>
    {
        users::Entity::find()
            .filter(users::Column::Email.eq(email))
            .one(&*DB::get()?)
            .await?
            .ok_or_else(|| FrameworkError::not_found("User"))
    }
}

// Call site:
pub async fn show(req: Request) -> Response {
    let email = req.param("email")?;
    let user = App::resolve::<UserService>()?
        .find_by_email(email)
        .await?;
    json_response!({ "user": user })
}

App::resolve::<UserService>()? returns Result<Arc<UserService>, FrameworkError>. The chained ? collapses both the resolve failure and the lookup failure to a response.

Cheat sheet

Next

• Error Model - variants, conversion contract, 5xx sanitisation, panic boundary, development error page
• Validation - #[derive(Validate)], form requests, and after_validation
• Responses - HttpResponse builders, status, headers
• Events - listening to ErrorOccurred and other built-in events
• Queue - retries, and the errors that end them
• Request Lifecycle - where in the request flow the error conversion runs