Mark a Flow as Failed Python

Overview

Use hud_sdk.set_failure() 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, soft-denies, or any condition you consider a failure.

When to Use

• The request/task completed but had a logical failure (e.g., missing required input, policy violation).
• You want Hud to record and surface a failure without raising an exception.
• You need consistent visibility across services that may handle errors silently.

⚠️

Important Notes

• The first argument should be a short, stable string describing the issue (e.g., "User did not provide an ID").
• Avoid unique or highly variable values (user IDs, timestamps, file names) so Hud can group failures effectively.
• You can attach optional key-value metadata for added context.
• Failure state is scoped to the current execution only.

Example #1: HTTP Handler

from flask import Flask, request
import hud_sdk

app = Flask(__name__)

@app.route("/checkout", methods=["POST"])
def checkout():
    items = request.json.get("items")
    if not items:
        hud_sdk.set_failure("Checkout attempted with no items")
        return {"status": "failure", "reason": "no items in cart"}

    # Continue with normal flow
    return {"status": "ok"}

Example #2: Queue Consumer

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

    # Normal handling logic here
    ...