The error signal captures when users encounter errors on your site, helping marketers identify and segment users who experience issues during critical processes. This enables targeted outreach and recovery campaigns for users who encounter obstacles.

Focus on high-impact errors:

• Payment errors
• Promo code validation failures
• Account registration issues
• Checkout process errors
• Any error that leads users away from the happy path and results in lost sales opportunities

📘

Important

The error signal doesn't replace error monitoring solutions. Its purpose is to enable marketers to segment users who experienced issues and deliver personalized recovery messages.

Availability: Premium and Ultimate

Implementation considerations

Error types

Two error types are supported.

User errors - Caused by user input that doesn't pass validation:

• Form validation failures
• Incorrect payment details
• Invalid promo codes
• Missing required fields
• Format errors (invalid email, phone number, etc.)

Application errors - Generated by the application itself:

• 4xx error pages (404, 403, etc.)
• 5xx server errors
• System failures
• API errors

Detection strategies

User errors:

• Check for error messages after form submission.
• Listen for validation feedback elements appearing in the DOM.
• Monitor error message containers on page load (if page reloads on submission).

Application errors:

• For 4xx/5xx errors, your application must display error placeholder pages that include the Connect library.
• The library cannot capture errors if it doesn't load on the error page.

Surface visibility

Make sure all important user errors are communicated in the interface. If something happens silently without user-facing feedback, it won't be captured by this signal.

Configuration

Method

TLT.logSignal(signalObject)

Sends the signal to the Acoustic Connect endpoint as a JSON object. The Connect library must be initialized before calling this method.

Signal structure

Top-level fields

• category: String - Valid value - Behavior.
• description: String - Description of the signal
• effect: String - Describes the effect of the signal on engagement. Valid values: negative, positive. Use negative for all error signals.
• name: String - Name to differentiate this signal from others (for example, "error from website"). Max length - 256 chars.
• signalType (required): String - Valid value - error.

Signal content

• errorIdentifier: String - An identifier assigned to the error (for example, "promoCode", "payment", "registration")
• errorText (required): String - The content of the error message received
• errorType (required): String - Type of error. Valid values: APPLICATION, USER.
• signalCustomAttributes: Array of objects - Additional custom attributes. Each object has name and value string fields.

Notes:

• If any required field is missing or invalid, the entire signal will be discarded.
• Optional fields enhance the signal but won't prevent processing if omitted or invalid.

Basic example

const signal = {
    // Required fields
    signalType: "error",
    category: "Behavior",
    name: "error from website",
    errorType: "user",
    errorText: "Invalid promo code",
    errorIdentifier: "promoCode",
    effect: "negative"
};

// Send the signal
TLT.logSignal(signal);

Complete implementation example

This example captures promo code and payment errors during checkout.

// Check that the Connect SDK is present
if (window.TLT && window.TLT.isInitialized()) {
    const signal = {
        signalType: "error",
        category: "Behavior",
        name: "error generated by website",
        errorType: "",
        errorText: "",
        errorIdentifier: "",
        effect: "negative"
    };

    const href = window.location.href;

    // Capture coupon code errors from query string
    if (href.includes("/checkout/?CouponCodeErrorMessage=")) {
        signal.errorText = href.split("checkout/?CouponCodeErrorMessage=")[1];

        if (signal.errorText) {
            // Clean up the message text
            signal.errorText = signal.errorText.replaceAll("%20", " ");
            signal.errorType = "user";
            signal.errorIdentifier = "promoCode";

            console.log("error signal:", JSON.stringify(signal, undefined, 2));
            window.TLT.logSignal(signal);
        }
    }

    // Capture payment errors on checkout page
    // These appear after page reload when form submission fails
    if (href.includes("/checkout/")) {
        const errorElement = document.querySelector('form[action="/checkout/Payment/"] > div.notice-error');

        if (errorElement) {
            signal.errorText = errorElement.innerText || "";

            if (signal.errorText) {
                // Clean up the message text
                signal.errorText = signal.errorText.replaceAll("\n", " ");
                signal.errorType = "user";
                signal.errorIdentifier = "payment";

                console.log("error signal:", JSON.stringify(signal, undefined, 2));
                window.TLT.logSignal(signal);
            }
        }
    }
}

Best practices

Use descriptive identifiers - Make errorIdentifier values clear and consistent (for example, "payment", "promoCode", "registration").

1. Clean error text - Remove unnecessary characters, newlines, or encoding artifacts before sending.
2. Consider timing - Some errors appear immediately, others after page reload. Adjust your detection logic accordingly.
3. Test error paths - Verify signals fire correctly by intentionally triggering errors during testing.
4. Don't duplicate error monitoring - This signal is for marketing segmentation, not technical debugging.

Troubleshooting

Signals not firing for errors?

• Verify error messages are visible in the DOM when you check for them.
• Check timing - errors that appear after async operations may need setTimeout.
• Confirm the Connect library loads on error pages (especially 4xx/5xx pages).
• Use console.log() to verify error elements are found.

Application errors not captured?

• Ensure your application displays error placeholder pages (not browser default pages).
• Verify the Connect library is included on all error page templates.
• Check that the library initializes successfully on error pages.

Error text looks garbled?

• Clean up URL encoding (replace %20 with spaces).
• Remove excess whitespace and newlines.
• Trim leading/trailing spaces.

Too many duplicate signals?

• Check if error messages persist across page loads.
• Add logic to prevent re-firing on page refresh.
• Consider using session storage to track already-reported errors.