# error Action

The `error` action provides a simple and consistent way to handle errors throughout the configuration.

It terminates the flow, sets its body template result as [`$error`](https://sevenval.gitbook.io/flat/variables#usderror) and calls the [error flow](https://sevenval.gitbook.io/flat/openapi-4/routing#error-flow), if configured, or sends the [system error document](https://sevenval.gitbook.io/flat/openapi-7/validation#system-error-document) with the body template result as the value of the `error` property.

In its simplest form, an error is triggered like this:

```markup
<error/>
```

To make errors more useful, they should contain a message:

```markup
<error>
{
  "message": "Upstream system sent unusable data"
}
</error>
```

## Error Properties

The action body contains a constant JSON string or a [JSON template](https://sevenval.gitbook.io/flat/reference/templating) representing a JSON object. The object will be assigned to the `$error` variable.

The following properties of the `$error` object are optional, but must have the specified type if set. If not set, they will receive the following default values:

* `message`: `string`, default: `'FlowError'`
* `status`: `integer` between 100 and 599, default: `500`
* `code`: `integer` between 0 and 9999, default: `5000`
* `info`: `array` of `string`, default: `["Flow Error triggered"]`

Additional properties are allowed. They will be accessible in the Error Flow. The following example includes the URL in `$error/url`:

```markup
<error>
{
  {{: $request/url }}
  "message": "Upstream system sent unusable data",
  "status": 502,
  "code": 4711
}
</error>
```

## Status Code

The `status` property will be used as the HTTP response status code. The status code may alternatively be defined with the optional `status` attribute.

```markup
<error status="403"/>
```

```markup
<error status="502">
{
  "message": "Upstream system sent unusable data"
}
</error>
```

## Fixed message shortcut

If the action body is a string constant (it must be enclosed in double quotes), its value will be assigned to the `$error/message` property. This is a handy shortcut to trigger simple errors with fixed messages:

```markup
<error status="502"> "Upstream system sent unusable data" </error>
```

## Logging

The `error` emits an [error log](https://sevenval.gitbook.io/flat/administration/logging#error-log) event with the `error` topic and the given `message`:

```javascript
{
  "timestamp": "2020-05-19T16:27:46+00:00",
  "type": "flat_alert",
  "requestID": "XsQJAMvNgp1P2qKAxKmdaAAAAAI",
  "topic": "error",
  "message": "Upstream system sent unusable data"
}
```

## See also

* [Error Flow](https://sevenval.gitbook.io/flat/openapi-4/routing#error-flow)
* [`$error`](https://sevenval.gitbook.io/flat/variables#usderror)
* [Handling Errors](https://sevenval.gitbook.io/flat/cookbook/error-flow) (Cookbook)