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

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:

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:

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

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:

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

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:

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:

{
  "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.) Otherwise, errors thrown by the THROW function be logged everywhere automatically-generated errors are. For instance, when Previewing, 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 Action, or used in as input within an 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:

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

Throwing custom errors can also be an important component of App APIs, depending on the use case.