Error Handling & Retry

Error Handling & Retry

Module Response States

Every module execution returns one of three states:

State	Meaning	Effect
DONE	Success	Execution continues; output is available to downstream steps
FAIL	Error	Play moves to FAIL state (unless retry succeeds)
SKIP	Skipped by module logic	Execution continues; output is empty

The FILTERED state is set by the platform when a flowlet’s filter conditions evaluate to false — the module never runs.

Retry Configuration

Configure retries per flowlet:

{
  "retry": {
    "count": 3,
    "delayMs": 1000,
    "backoffMultiplier": 2.0,
    "jitter": true
  }
}

Retry sequence example (count: 3, delayMs: 1000, backoffMultiplier: 2):

1. Initial attempt — fails
2. Wait ~1000ms → retry 1 — fails
3. Wait ~2000ms → retry 2 — fails
4. Wait ~4000ms → retry 3 — if still fails → play FAIL

With jitter: true, each delay is multiplied by a random factor (0.8–1.2) to spread load.

Timeout

{"timeout": 30}

If the module doesn’t respond within 30 seconds, it fails with execution timeout. Retry logic applies.

Conditional Execution (Filters)

Use filters to skip steps based on previous results:

{
  "ref": "sendFailureAlert",
  "appId": "send-mail",
  "filters": [
    {
      "leftValue": "{{ $prev.processPayment.success }}",
      "operator": "eq",
      "rightValue": "false"
    }
  ]
}

This step only runs when payment processing fails.

Error Handler Pattern

Connect a dedicated error-handling branch by checking the play state in downstream filter conditions:

Step 0: processData (index: 0)
Step 1: saveResult  (index: 1, filter: $prev.processData.state == DONE)
Step 2: notifyError (index: 1, filter: $prev.processData.state == FAIL)

Both steps at index 1 run in parallel — one handles success, one handles failure.

Global Error Flow

Configure a flow-level error handler that runs whenever any step fails:

{
  "execution": {
    "onFailFlowId": "65error-handler-flow-id"
  }
}

The error handler flow receives the failed play’s context as input.

Catching Specific Errors

Module outputs often include error details in their out field even on failure. Check these in downstream filter conditions:

{{ $prev.apiCall.statusCode }}   ← HTTP status code
{{ $prev.apiCall.error }}        ← Error message string

Filter on these to handle specific scenarios:

{
  "leftValue": "{{ $prev.apiCall.statusCode }}",
  "operator": "eq",
  "rightValue": "429"
}