Connector Failed¶

Outcome: Understand why an action failed and fix it. Audience: Everyone · Tags: troubleshooting, connector, failure

Your flow ran, but an action (send an email, post to Slack, make a REST call, …) failed. The run shows failed (or retry_exhausted), and the failing step carries an error code that tells you exactly what kind of problem it was.

Symptoms¶

A run shows failed or retry_exhausted.
A step is marked failed in the run's timeline.
The expected effect (message sent, record created, request delivered) didn't happen.

Step 1 — Read the error code¶

Open the run (via the Flow Debugger, or GET /api/v1/flow-designer/debug/:runId) and find the failing step's error code. This table is the complete list — every failed step has exactly one of these:

Code	Meaning	Fix
`auth`	A credential is missing, expired, or invalid.	Reconnect the app: Marketplace → the connector → reinstall/reconfigure. For the Email connector, this means the operator's `SMTP_*` environment variables aren't set — ask your administrator.
`rate_limit`	The destination app throttled the request.	Slow down, or add a retry policy to the flow so SnapLink backs off automatically.
`timeout`	The destination was too slow to respond.	Retry; check whether the destination app is having issues.
`upstream_5xx`	The destination returned a server error.	Retry later; check the destination's status page — this is usually not something wrong on your end.
`bad_request`	The action's inputs were wrong or incomplete.	Check the flow's field values — a required field is empty, or a value is in the wrong shape.
`blocked`	A URL was blocked by SSRF protection.	Use a public `https` address, not a private/internal/loopback one.
`unknown`	Something unexpected happened.	Open the run in the debugger; if it repeats, contact support with the run ID.

Step 2 — Read the debugger's own explanation¶

The Flow Debugger reads the same data the execution engine recorded — it doesn't guess. For a run, it returns:

connectorInvocations — one entry per step actually attempted, each with the connectorKey, capability (the action type), status, attempt number, and errorCode. If a step was retried, you'll see its later attempts here too.
failureCause — a plain description of what failed (built from the failing step's connector, action, and error code, or the run's own recorded failure reason).
suggestedFix — one plain sentence matched to the failing step's error code (the same fixes summarized in the table above).

curl -s https://api.snaplink.cloudsolutionaccelerators.com/api/v1/flow-designer/debug/<runId> \
  -H "Authorization: Bearer $TOKEN"

Read suggestedFix first — it's tailored to exactly what happened, not a generic tip.

Connector-specific notes¶

Email (SMTP) — an auth error here almost always means the operator hasn't set SMTP_HOST / SMTP_PORT / SMTP_USER / SMTP_PASS / SMTP_FROM yet. This isn't something a flow author can fix from inside a flow — ask your administrator. See Email connector.
REST connector — a blocked error means the target URL resolved to a private, loopback, link-local, or cloud-metadata address, which SSRF protection refuses to call. Use a public https endpoint. See REST connector.
Slack / Teams / HubSpot — these connectors are in Early Access. Installing/connecting them validates and stores a connection, but completing live OAuth against the real vendor API requires a registered app (client id/secret) configured by your administrator. Until that's set up, calls from these connectors fail with auth even though the connector shows as installed — this is expected in Early Access, not a broken connection. See each connector's page (Slack, Teams, HubSpot) for current status.

Step 3 — Re-run¶

After fixing inputs or reconnecting, trigger the flow again, or use Retry on the failed run (this starts a fresh run — see Execution failures). Confirm the new run succeeds and the expected effect shows up in the destination app.

Advanced diagnostics¶

The run's timeline shows every step, its attempt number, error code, and timing, top to bottom.
retry_exhausted means every retry attempt failed — the recorded cause is the last attempt's error, not necessarily the first.
Failure reasons are sanitized: SnapLink never logs or returns secrets, full request bodies, or full response bodies in a failure detail.

When to contact support¶

The error code is unknown and repeats, or a step fails with inputs you're confident are correct and a connection that shows healthy. Include the run ID, the flow name, and which step failed.

Was this helpful? 👍 👎