User-Defined Errors (Mark a Flow as Failed)

Overview

Use setFailure() (Node.js) or set_failure() (Python) to explicitly mark the current execution as failed even if no exception occurred and the issue was not auto-detected. This is useful for business-rule failures, invalid input that you handle gracefully, or any condition you consider a failure.

Once marked, the flow is counted in your error rate, grouped into issues by failure message, and visible in forensics and alerts.

Requirements

SDK	Minimum version	Supported flow types
Node.js	`1.8.2`	Endpoints, Queues
Python	`0.4.2`	Queues

Implementation

Setup

const hud = require("hud-sdk/api");

//Alternative
import { setFailure } from "hud-sdk/api";

import hud_sdk

Example: HTTP Endpoint

const hud = require("hud-sdk/api");
const express = require("express");
const app = express();

app.post("/checkout", (req, res) => {
  const { items, paymentMethod } = req.body;

  if (!items || items.length === 0) {
    hud.setFailure("Checkout attempted with no items");
    return res.status(400).json({ error: "No items in cart" });
  }

  const paymentResult = processPayment(paymentMethod, items);

  if (!paymentResult.success) {
    hud.setFailure("Payment failed", {
      reason: paymentResult.reason,
      provider: paymentResult.provider,
    });
    // Note: returns 200 — the server handled it, but Hud counts it as a failure
    return res.status(200).json({
      status: "payment_failed",
      reason: paymentResult.reason,
    });
  }

  res.json({ status: "ok", orderId: paymentResult.orderId });
});

import hud_sdk

def process_message(msg):
    if msg.get("type") not in ["create", "update"]:
        hud_sdk.set_failure("Unsupported message type", message_type=msg.get("type"))
        return

    result = handle_message(msg)

    if result.get("skipped"):
        hud_sdk.set_failure("Message processing skipped", reason=result.get("reason"))
        return

    # Normal handling logic
    ...

API Reference

setFailure(error: string, context?: {string: number | string | bool}): void

hud_sdk.set_failure(error: str, metadata: dict[str, int | str | bool]) -> None

Instructions

Keep failure messages stable. "Payment provider timeout" groups well. "Payment failed for user 12345 at 2026-05-20T10:30:00" creates a new issue for every occurrence.
Use context for variable data. Put user IDs, request IDs, and other variable data in the context parameter instead of the error string.
One call per flow. If you call the method multiple times in the same flow, the last call is recorded.

Notes

Works with any HTTP status. The flow is marked as failed regardless of the response status code. If the flow also returns 5xx, it is counted once (not double-counted).
No rule configuration needed. Existing Endpoint Error and Post-Deploy Error rules automatically detect user-defined failures.