5.12 Error Handling, Retry & Compensation Mechanisms

Error handling is a critical part of ensuring workflow stability. Pop Workflows provide built‑in multi‑level error capturing, automatic retry, and compensation mechanisms, helping you handle issues such as:

• Third‑party API instability
• AI model timeout / rate limiting
• File I/O errors
• Invalid user inputs
• PSL script exceptions
• Business condition failures causing interruptions

This chapter covers all error‑handling functions and techniques in Pop.

---

🔍 1. Types of Errors in Workflows

During workflow execution, the following error types may occur:

Error Type	Description	Common Scenarios
Config Error	Missing or invalid node configuration	Missing model / URL / required fields
Input Error	Upstream data formatting issues	Empty value, type mismatch
PSL Error	Exception thrown during PSL execution	Null reference, invalid property access
Runtime Error	External runtime failures	HTTP timeout, missing file
Business Error	User‑defined failure conditions	Status code incorrect, result not satisfied

The Pop execution log clearly displays error type, stack trace, and node location for quick debugging.

---

🔁 2. Node‑Level Automatic Retry

Many nodes support an automatic retry strategy for handling intermittent failures (network instability, AI timeout, etc.).

You can configure these in the node properties panel:

Setting	Description
retryCount	Default 0; can be set to 1–5
retryInterval	Milliseconds between retries
retryCondition (optional)	Trigger retry only for specific errors

Suitable for:

• AI request timeout
• Occasional HTTP failures
• Delayed file reads
• Network‑related I/O problems

Example:

retryCount: 3
retryInterval: 1000

---

🛑 3. Error Capturing (Try‑Catch Node)

For fine‑grained error control, you can use the Try / Catch node.

Structure:

[Try Node]
    ↓ if error
[Catch Node]

Use cases:

• Capture all exceptions from a node or subflow
• Run compensation logic in the Catch node
• Send alerts (SMS, email, Feishu, Webhook)
• Continue workflow without interruption

Example Catch output:

{
  "error": {
    "message": "HTTP request failed",
    "stack": "...",
    "node": "http-request-2"
  }
}

---

🔄 4. Compensation Nodes

Compensation logic is used:

To perform rollback, undo, or notification when a step fails.

Typical scenarios:

• Database write failed → rollback cache
• Third-party API failure → send notifications
• File move failed → restore original file
• Document generation failed → clean up temp files

Compensation is usually implemented using:

• Script nodes (undo logic)
• HTTP/Webhook notifications
• File nodes (restore file state)
• Custom compensation modules

Example compensation script:

globals.set("rollback", true);
return { status: "rolled_back" };

---

🧩 5. Fail‑Safe Nodes

For scenarios where you want:

• Workflow to continue even when a step fails
• Provide default fallback data

Use:

Safe Node

It has two outputs:

success → success
failure → fallback

Useful for:

• AI timeout → use default answer
• HTTP failure → use cached data
• File read failure → continue with empty value

Example:

fallbackValue: { "useCache": true }

---

🧪 6. Error Handling in PSL

PSL provides try/catch‑style logic:

try {
  const data = nodes.sn(5).output.items;
  return { ok: true, items: data };
} catch (e) {
  return { ok: false, error: e.message };
}

This ensures script nodes return safe structures and do not interrupt workflow execution.

---

🧭 7. Error Debugging Techniques

✔ 1. Check Red Nodes

Nodes with errors turn red. Expand logs to view stacks.

✔ 2. Run “Execute This Node”

Debug step‑by‑step.

✔ 3. Use Dictionary Node to Print Debug Values

{
  "debug_input": {{input.first}},
  "node_output": {{nodes.sn(8).output}}
}

✔ 4. Use Branch Node to Validate Conditions Early

Examples:

• If a value is empty → go error branch
• If status code incorrect → go fallback

---

🧱 8. Best Practices for Workflow Robustness

Suggestion	Description
Provide default values	Avoid null‑related script errors
Enable retry on external requests	For AI / HTTP / network file I/O
Use Try‑Catch to isolate failures	Local failures won’t stop entire flow
Break large tasks into modules	Easier debugging, reuse, isolation
Use modules for idempotency	Prevent repeated side effects
Record errors to log center	For later troubleshooting

---

🎯 9. Summary

Pop’s error‑handling framework includes:

• Automatic retry
• Try/Catch error capturing
• Compensation logic
• PSL exception safety
• Fail‑Safe execution
• Flexible branching & default values
• Fully traceable execution logs

Mastering these tools will help you build more reliable, stable, and maintainable automated workflows.