Errors, retries and timeouts

This page covers two kinds of failure: a step that fails inside a run, and an API request that Loopfour refuses. The plain-language guide for people reviewing runs is Fix a failed run.

When a step fails

Each step can carry an errorHandling object:

{
  "id": "sync_customer",
  "type": "action",
  "name": "Update the CRM record",
  "action": "hubspot.updateContact",
  "config": { "...": "..." },
  "errorHandling": {
    "strategy": "continue",
    "fallback": { "synced": false }
  }
}

With continue, the step's output becomes:

• without a fallback: { "error": true, "message": "<error message>" };
• with a fallback: the fallback fields, plus message and originalError set to the error message.

When the failing action names the records behind the failure, the output also has them in details, for example {{steps.sync_customer.details.<field>}}. An action keeps only short text, finite numbers and true/false values there, so a field can be missing.

A later Condition step can branch on it, for example { "left": "{{steps.sync_customer.error}}", "operator": "eq", "right": "true" }.

Rejected approvals

A rejected Approval step, or one that times out without approval, fails the step and stops the run. With strategy: "continue" the run goes on, and the step's output holds the decision plus error: true and a message.

Retries and timeouts per step

The step schema accepts retryConfig and timeoutMs, but the run engine does not apply them today, and a failed run is not retried on its own. Retries happen inside a block instead:

• Some integration actions retry a provider call on their own when it answers 408, 429 or a 5xx status, or on certain network errors. By default only repeat-safe methods (GET, HEAD, PUT, DELETE) are retried, so a POST that creates a record is not sent twice. Whether an action does this is set per action.
• The API Request block has its own retry and timeout settings.

To limit a whole run, set settings.maxDurationSeconds on the workflow (minimum 5). The run is stopped when the limit is reached. See Settings.

Step error codes

A failed step's entry in the run's stepResults has an error object with a code and message:

A run that cannot find a secret it references fails with the message Missing required secrets: <keys>.

Retry or restart a failed run

Retry and restart answer 400 with code INVALID_STATE for a run that is still live. Branch on error.code, not on the HTTP status. The full request and response shapes are in the Runs API.

API error responses

Most errors share one envelope:

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Workflow not found",
    "requestId": "req_7f3a...",
    "details": { }
  }
}

details is present only on some errors. Quote requestId when you contact support.

Request body validation

When a request body does not match an endpoint's schema, the 400 body lists each problem instead of a code:

{
  "success": false,
  "error": {
    "name": "ZodError",
    "issues": [
      { "path": ["steps"], "message": "Too small: expected array to have >=1 items" }
    ]
  }
}

Read issues[].path to find the field.

Inbound webhook routes

The /webhooks/... routes do not use the envelope. They answer with a short body such as { "error": "Invalid signature" } (401) or { "error": "Unknown provider: <name>" } (404). See Webhook trigger.

Retry your own requests safely

• Retry 429, 502, 503 and network errors with a growing wait. On 429, wait at least Retry-After seconds.
• Do not retry other 4xx responses unchanged; fix the request first.
• Send an idempotencyKey with POST /workflows/:id/run. A repeat with the same key for the same workflow returns the existing run instead of starting a second one.