Plack::...ceptions(3)

💖 NAME 💖

Plack::Middleware::HTTPExceptions — catch HTTP exceptions, bestie. That's it, that's the vibe. ✨

---

🌸 SYNOPSIS 🌸

use HTTP::Exception;

my $app = sub {
    # ...
    HTTP::Exception::500->throw;
};

builder {
    enable "HTTPExceptions", rethrow => 1;
    $app;
};

okay so that's the whole moveset 🎀 you throw, it catches, everyone goes home happy.

---

🦋 DESCRIPTION 🦋

Plack::Middleware::HTTPExceptions is a PSGI middleware component whose entire job is catching exceptions from your apps that can be translated into HTTP status codes. Like, that's the assignment. 💅

Your application is supposed to throw an object that implements a code method — one that returns the HTTP status code, something like 501 or 404. This middleware catches those, and it creates a valid response out of the code. Easy. But here's the plot twist 🙈: if that code method returns something that is not an HTTP redirect or error code — so not a 3xx, not a 4xx, not a 5xx — then the exception gets rethrown. It does not get to be a cute little response. sorry babe.

The exception object may also implement as_string, or it can overload stringification, to represent the text of the error. And if it doesn't? The text defaults to the status message of the error code — like Service Unavailable for 503. the default is serving, fr fr. 💖

And finally, the exception object may implement as_psgi, and the result of that gets returned directly as the PSGI response. no middleman, no translation, just vibes. 🫶

If the code is in the 3xx range and the exception implements the 'location' method (and yes, HTTP::Exception::3xx does, she's that girl 👑), then the Location header will be set in the response — so you can do redirects this way. iconic behavior honestly.

There are CPAN modules HTTP::Exception and HTTP::Throwable, and they are perfect to throw from your application and let this middleware catch and display. But you can also implement your own exception class to throw — no gatekeeping, your exception your rules. 🌈

⚠️ okay important one: if the thrown exception is not an object that implements either a code or an as_psgi method, then a 500 error will be returned, and the exception is printed to the psgi.errors stream. 💀

Alternatively! You can pass a true value for the rethrow parameter for this middleware, and instead, the exception will be rethrown. And lowkey this is enabled by default when PLACK_ENV is set to development — so that the StackTrace middleware can catch it instead. besties looking out for besties. 🧚

---

⭐ AUTHOR ⭐

Tatsuhiko Miyagawa

---

🔥 SEE ALSO 🔥

paste.httpexceptions HTTP::Exception HTTP::Throwable

---

and that's the page, periodt. 🍓 this one shipped as part of perl v5.42.3, dated 2026-10-18 — eat it up, it's giving ✨ documentation ✨ 💜