# THROW

**The function THROW throws an error, halting evaluation and providing identifying error details based on the given input.**

\[block:callout] { "type": "info", "body": "The THROW function is unique among Airscript functions in that it halts evaluation, preventing it from returning any output. Input given to the THROW function, describing the error identifier, the error message, and, optionally, any metadata pertaining to the error will be incorporated into the error details as well as the error message." } \[/block]

#### Declaration

```javascript
THROW(error_identifier, error_message, error_metadata) -> input_value
```

#### Parameters

**error\_identifier** (required, type: `string`) The error identifier.

**error\_message** (required, type: `string`) The error message.

**error\_metadata** (optional, type: `object`) Metadata pertaining to the error.

#### Return Values

This function halts evaluation, preventing it from returning any values.

#### Examples

When called correctly, the THROW function will throw an error:

```javascript
THROW(
    "Unexpected response status", 
    "Found wrong response status."
) -> ERROR
```

The error thrown by a correctly-called THROW function, however, will differ from an error thrown by an incorrectly-called THROW function, in that the given input will be used to generate the error details. For instance, in the case of the above expression, the error details will appear as follows. Note that the value of `metadata.identifier` matches the `error_identifier` given in the expression above; likewise, `metadata.message` matches the given `error_message`:

```javascript
{
  "airkitErrorType": "ApplicationError",
  "sourceProject": XXX,
  "name": "ApplicationError",
  "identifier": "error.application.user-defined-error",
  "metadata": {
    "identifier": "Unexpected response status",
    "message": "Found wrong response status.",
    "metadata": {},
    "url": XXX,
    "statusText": "",
    "statusCode": 400
  },
  "httpStatus": 400
}
```

The THROW function can optionally accept metadata in the form of an object. This object can consist of any number of key-value pairs:

```javascript
THROW(
  "Unexpected response status",
  "Found wrong response status.",
  {
    expected_status: FALSE,
    error: TRUE
  }
) -> ERROR
```

The error details of the above expression will appear as follows. Note that the value of `metadata.metadata` matches the value of `error_metadata` given in the expression above:

```javascript
{
  "airkitErrorType": "ApplicationError",
  "sourceProject": XXX,
  "name": "ApplicationError",
  "identifier": "error.application.user-defined-error",
  "metadata": {
    "identifier": "Unexpected response status",
    "message": "Found wrong response status.",
    "metadata": {
      "expected_status": false,
      "error": true
    },
    "url": XXX,
    "statusText": "",
    "statusCode": 400
  },
  "httpStatus": 400
}
```

Airscript expressions can be used to generate more specific values for identifiers, messages, or metadata. For instance, say the following expression have access to the variable `found_status`, which is defined as follows:

```javascript
found_status = "Pending"
```

This variable can be used to generate an error message that displays the found status in addition to flagging the status as unexpected:

```javascript
THROW(
  "Unexpected response status",
  "Status found: {{found_status}}"
) -> ERROR
```

The error details of the above expression will appear as follows. Note how the value of `metadata.message` appears:

```javascript
{
  "airkitErrorType": "ApplicationError",
  "sourceProject": XXX,
  "name": "ApplicationError",
  "identifier": "error.application.user-defined-error",
  "metadata": {
    "identifier": "Unexpected response status",
    "message": "Status found: \"Pending\"",
    "metadata": {},
    "url": XXX,
    "statusText": "",
    "statusCode": 400
  },
  "httpStatus": 400
}
```

#### Discussion

Unlike most Airscript functions, THROW is not used for data manipulation. It is instead meant to aid in the app-testing process by making errors more legible. Errors thrown via the THROW function cannot be sent as App Notifiers. (If you need to send a notifier in response to a custom error, use a [Custom Event Error](../../error-managment/logging-errors).) Otherwise, errors thrown by the THROW function be logged everywhere automatically-generated errors are. For instance, when [Previewing](../../studio/studio/app-preview), errors thrown by the THROW function will be flagged as errors in the Event Log Viewer.

The THROW function is commonly used in tandem with conditionals incorporated directly into a Journey. For instance, it might be part of a branching [Condition](../../actions/the-condition-action) Action, or used in as input within an [IF](../conditional-functions/if) function to perform validation.

As a more concrete example, the THROW function can be used to thrown an error if some date variable (`input_date`) indicates a date before the present day:

```javascript
IF(
  input_date
    < DATE_FROM_DATETIME(NOW()),
  THROW(
    "Date is too old!",
    "Date is {{
      FORMAT_DATE(
        input_date,
        "YYYY/DD/MM"
      )
    }}"
  )
)
```

Such validation expressions will usually be lengthy, and we recommend incorporating them into [User Defined Functions](../advanced-expressions/udf) when possible.

Throwing custom errors can also be an important component of [App APIs](../../integration-guides/application-apis), depending on the use case.
