> ## Documentation Index
> Fetch the complete documentation index at: https://docs.leapter.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Handling

> Name the ways your logic can fail with error types, raise them where a rule is broken, and handle them with a business fallback — or let them reach the caller.

Some situations mean a Blueprint cannot produce a sound result — an application without an income, a product that is not on the price list. Leapter lets you name these situations as **error types**, raise them where they happen, and decide what to do about them: handle them with a business fallback, or let them reach whoever called the Blueprint.

## The idea in one example

The Loan Application Scorecard example uses one error type, `InvalidApplication`:

* **Defined** — `InvalidApplication` is an Error in the [Type Definitions](/editor/type-definitions), with a `message` and the `field` that needs correcting.
* **Raised** — the private **Calculate Score** Blueprint raises it when the monthly income is 0 EUR, because no score can be calculated without an income.
* **Handled** — the **Loan Application Scorecard** Blueprint handles it: an application that cannot be scored goes to manual review instead of failing.
* **Not handled** — the **Quick Affordability Check** Blueprint raises it too but does not handle it, so a caller of that Blueprint receives the error.

## Define an error type

An error type is created like any other type — in the **Type Definitions** chapter (**Add an error type**) or with **Error** on the type canvas. See [Type Definitions](/editor/type-definitions).

Every error type has a `message` field that explains the failure in plain words. Add the fields a caller needs to react, for example the name of the input that was wrong. Name the type after the situation, such as `InvalidApplication` or `LimitExceeded`.

## Raise an error

To stop a Blueprint with an error, add the element **Return blueprint with an error** from the [element palette](/elements/controlling-the-flow). In the element, choose the error type after **Fail with** and fill in its fields — at least the `message`.

When a run reaches this element, the Blueprint stops. What happens next depends on whether a section on the way out handles the error:

* **Handled** — the handler's steps run, and then the run continues after the handled section.
* **Not handled** — the run ends with the error. If the Blueprint was called by another Blueprint, the error passes on to that caller. If it was called through the [REST API](/release-and-integrate/connect-rest-api), the call returns HTTP status 500 with the title **Run Error**, and the response's `properties` name the error type and carry its message and fields — so the caller can tell this failure apart from others. The run is listed as an error in [Insights](/release-and-integrate/insights).

A [Call node](/elements/calling-other-blueprints) shows which errors the called Blueprint can raise with a pill such as **can raise InvalidApplication**. Click it to see whether the error is handled, and where.

## Handle an error

You handle errors per section:

1. In the [Specification view](/editor/specification-view), open the **⋮** menu of the section whose failure you want to handle and choose **Handle an error** ("When this section fails with an error").
2. Pick the error type to handle, and name the handler.
3. Add the steps that should run instead — usually setting the outputs to a sensible fallback.

<img src="https://mintcdn.com/leapter/7EqC4xHUro9F4teL/images/error-handling-spec.png?fit=max&auto=format&n=7EqC4xHUro9F4teL&q=85&s=d209e84255f571632c2c6922fe47821d" alt="The Assess the Application section with Handles: InvalidApplication, followed by its handler Send unscorable applications to review — Catches InvalidApplication as problem, Handler of Assess the Application — with four steps that set the score, risk, decision, and review action" width="700" height="990" data-path="images/error-handling-spec.png" />

The section shows which errors it handles (**Handles:**), and the handler appears as its own chapter that reads **Catches** *ErrorType* **as** *name*, followed by **Handler of:** and the section. In the diagram, the handler is drawn as a red **On error** region below the section.

Inside the handler, the name after **as** holds the caught error, so you can use its fields — for example, to record why the application went to review.

### Rules for handlers

* A failure raised anywhere inside the section — including inside a Blueprint the section calls — goes to the nearest enclosing section that handles that error type.
* A handler catches exactly the error type it names. To catch every error type, choose **any error**; put it last, after the handlers for specific types.
* Only handle an error where you have a real fallback. An error that no handler catches reaches the caller, which is often exactly right.
* Technical faults — such as dividing by zero — are not errors in this sense. No handler catches them, and the run fails.

## Test for errors

A test case can expect an error instead of outputs. In the test case, set the **Expected Error**: the **Error type**, and optionally the **Expected error fields**. The test passes when the Blueprint raises exactly that error. See [Test Suites](/test-and-validate/test-suites).

## What to do next

* **[Type Definitions](/editor/type-definitions)** — define your error types
* **[Controlling the Flow](/elements/controlling-the-flow)** — the other elements of a Blueprint
* **[Test Suites](/test-and-validate/test-suites)** — make sure each error is raised when it should be


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.