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 and calls the error flow, if configured, or sends the 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:

<error/>

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

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

Error Properties

The action body contains a constant JSON string or a JSON template 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:

<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.

<error status="403"/>

<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:

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

Logging

The error emits an error log event with the error topic and the given message:

{
  "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

• $error

• Handling Errors (Cookbook)