Overview

Use host.http.error(...) (or g.error(...) inside a route group) to map thrown errors in the HTTP pipeline to client responses.

For defining FlareError instances and error registries, see Typed errors. For the full failure catalog, see Failure modes.

Two authoring styles

Style	Registration
Inline function	host.http.error(fn) or host.http.error(options, fn)
Class	host.http.error(ErrorHandlerCls) extending ErrorHandlerBase

See Inline error handlers and ErrorHandlerBase classes.

Return contract

The first handler that returns a FlareResponse or web Response wins. Return void or undefined to defer to the next handler, then to the default fallback.

Thrown FlareError with no matching handler maps automatically by category (not_found → 404, conflict → 409, and so on). Any other Error becomes 500 { error: "Internal Server Error" }.

What bypasses error handlers

These never enter host.http.error() dispatch:

• Unmatched paths (404)
• Method not allowed (405)
• Invalid pathname or route params (400)
• Contract validation failures (400 / 413)
• Pre-build 503 and Node shutdown 503
• CORS preflight short-circuit

The separation is the payoff. A single hand-rolled catch at the top of a request funnels every failure through one place: a malformed body, an unmatched route, and a genuine application conflict all arrive as the same caught value, and you re-derive the intended status by inspecting it. Miss a case and a bad request comes back as a 200-shaped apology, or a client mistake is logged as a server 500. Flare answers transport and contract failures with fixed responses that never enter host.http.error(), so the handlers you register run only for errors thrown from inside the pipeline, and decide only how such an error becomes a response.

Group scope

Group routes run arc-level handlers first, then handlers registered with g.error(). g.isolated() affects middleware only, not the error-handler chain.

Related

• Register a custom handler: how-to walkthrough
• HTTP contracts: boundary validation vs thrown errors