Execution Failures¶

Outcome: Understand a run's lifecycle, unstick a stuck run, and know when to retry vs. cancel. Audience: Everyone / Developers · Tags: troubleshooting, execution, retry

Run statuses (the whole set)¶

A run moves through exactly these states — there are no others:

queued → running → succeeded, or on error running → failed → (if a retry policy applies) retry_pending → retry_running → back to failed or on to succeeded. If retries run out, it ends in retry_exhausted. A run can also be ended early as cancelled.

succeeded, cancelled, and retry_exhausted are terminal — nothing further happens to that run automatically.

Symptoms → cause → fix¶

A run is stuck in `queued` or `running`¶

This should be brief. If a run sits in queued/running far longer than your flow's steps should take:

Open the run and check its timeline and events — see exactly which step it's on and when it last moved.
Check whether the step it's stuck on is one that's known to be slow (a REST call to a slow destination) — that will resolve as either success or a timeout failure, not stay stuck forever.
If it truly never resolves, this is unexpected — see When to contact support below.

curl -s https://api.snaplink.cloudsolutionaccelerators.com/api/v1/executions/<runId>/events \
  -H "Authorization: Bearer $TOKEN"
curl -s https://api.snaplink.cloudsolutionaccelerators.com/api/v1/executions/<runId>/audit \
  -H "Authorization: Bearer $TOKEN"

A run ended in `retry_exhausted`¶

Every retry attempt failed. The recorded failure is the last attempt's, not the first. Two error codes are never retried automatically, because retrying won't help until you fix something: auth and bad_request — see Connector failed for the full taxonomy and fixes. Fix the underlying cause, then use Retry.

I want to stop a run that's still going¶

Cancel it:

curl -s -X POST https://api.snaplink.cloudsolutionaccelerators.com/api/v1/executions/<runId>/cancel \
  -H "Authorization: Bearer $TOKEN"

Only a non-terminal run can be cancelled — trying to cancel a run that's already succeeded, cancelled, or retry_exhausted returns a 409 RUN_TERMINAL error, because there's nothing left to stop.

I want to re-run a failed flow¶

Retry it — this creates a brand-new run for the same flow (runs are immutable once terminal, so nothing about the old run changes):

curl -s -X POST https://api.snaplink.cloudsolutionaccelerators.com/api/v1/executions/<runId>/retry \
  -H "Authorization: Bearer $TOKEN"

Retry only works on a run whose status is failed, retry_exhausted, or cancelled — retrying a run that's still in progress, or one that already succeeded, returns a 409 RUN_NOT_RETRYABLE error.

Resolution steps (general)¶

Open the run in the Flow Debugger. Read the status, failure cause, error code, and suggested fix.
Fix by error code category — see Connector failed for the complete table.
Retry the run, or trigger the flow fresh.
To make a flaky flow more resilient long-term, add or raise a retry policy for transient codes (rate_limit, timeout, upstream_5xx).

Advanced diagnostics¶

The run's timeline lists each step and each attempt with timing — find the first step that actually failed, not just the last one reported.
Developers: GET /executions/:id, /events, /audit, and /steps give you the full recorded picture. Failure reasons are sanitized — no secrets or full request/response bodies are ever included.

When to contact support¶

A run stuck in queued/running for an unusually long time with no timeline movement, repeated unknown errors, or a result that doesn't match what the connected app actually shows. Include the run ID.

Related: Connector failed · Monitoring Runs · Flow Debugging

Was this helpful? 👍 👎