How does Ampscript RaiseError function work?

Salesforce Developers|Ampscript

The RaiseError function aborts the send (email and sms) and allows the generation of a custom error message. It is useful for exception handling in your code, if an unexpected result occurs.

When used in conjunction with a conditional statement, it helps to ensure that your email does not get sent if there are empty personalisation variables or bad / missing data. According to how you configure the function, it can either skip the send for the current subscriber and move on to the next subscriber, or it can stop the remaining send job.

This function should not be misused for purposes of data segmentation. Even though a subscriber is skipped or the whole job is cancelled, it previously counted towards your Super Message consumption, meaning that you will pay for each suppressed email as you would for a sent one. Current understanding is that this SM consumption is no longer the case!

UPDATE: April 2024
According to SF Support Case, RaiseError function does NOT consume super messages, they are NOT included in billing utilization counts.

Bear in mind, that the second property of the RaiseError() function will default to false if its not specified. So, unless it is set to true, it will always stop the remaining send job.

Arguments

RaiseError(1, 2, 3, 4, 5)

1. The custom error message to display once error is pushed.
2. Indicates if the function will continue throughout the dataset of your subscribers, or cancel the entire job. A value of true skips to the next subscriber, and false halts the process completely. The default value is false.
3. Custom user defined ‘API Error code’ that you can set. This is a string value for you to write a short descriptor for the error.
4. Custom user defined ‘API error number’. This number would mostly be used for your own reference only and does not affect anything else.
5. If you set this to 1 (true), then it will still allow all the processed information (via Update, Insert, Upsert AMPScript or SSJS functions) prior to RaiseError to be processed . Otherwise, if you set this to 0 (false) then any processed information that you had set prior to the RaiseError in your script will NOT be added in or updated. The documentation specifically calls out to use 1 or 0 — do not use true/false — use the integers.

To further elaborate on #5, think of it like this:

• With true, the Upsert Function in the example below on the first line will still process and the record will be upserted.
• With false, the Upsert Function will NOT be processed and the record will NOT be upserted even though the RaiseError() occurs later in the script.

%%[
    UpsertDE(@yourDE, 1, "pkey", @pkey, "attr1", @attr1)
    RaiseError("Broken", true, "Broken", 66, 1)
]%%

Viewing Errors

For Journey Builder or Triggered Sends, you can check the “Errored” column in within the TSD inside the Interactions tab within Email Studio. Alternatively, you can also get the same view in Tracking>Sends>Journey Builder Sends. Sadly, you won’t be able to view any details of the suppressed sends in the UI.

Otherwise, the emails and jobs suppressed by the RaiseError() function are visible in:

• Creating an SFMC Support Case specifying you wish to be provided with the Error Log.
• The NotSent tracking extract

Logging RaiseError results

Use InsertDE before the RaiseError to capture a specific error message for several cases. This way, each email suppressed by the RaiseError() function will also be logged in the Data Extension.

In order to log all aborted sends, you can create a Data Extension and add an InsertDE function to the email. Make sure to set the last property of the RaiseError() function to 1 and include the InsertDE() function before the RaiseError() function (as everything placed after won’t get executed). Make sure to create the DE without a primary key, so it will accept every entry.

DE Setup:

Date Extension Config

Email AMPscript:

IF RowCount(@rows) > 0 then
    /*code here*/
ELSE
    SET @error = "No coupons found"
    InsertDE('RaiseError_Log_DE_Name',
        'jobID', JobID,
        'subscriberKey', _SubscriberKey,
        'emailName', EmailName_,
        'errorMessage', @error
    )
    RaiseError(@error, true, "Missing a required field", 400, 1)
ENDIF

Photo by Erik Mclean on Unsplash