Flow Validation

Audience: Everyone / Developers · Tags: flow, validation, errors

Purpose. Before a flow definition is promoted, SnapLink can check it for problems — a connector that isn't installed, a required field left blank, a trigger type that doesn't exist — so you find out at draft time instead of from a failed run.

When to use. Any time you write or edit a flow definition by hand (Snap Studio runs this automatically as part of its check step — see AI Flow Drafting).

Every validation error code

POST /flow-designer/validate returns { valid: boolean, errors: [...] }. Each error has a code, a message, and usually a location (the action key it applies to).

Code	Plain meaning	What to do
invalid_structure	The definition JSON isn't shaped correctly (missing trigger/actions, wrong types, etc.)	Compare your JSON against the shape in Creating Flows and fix the structure.
unsupported_trigger	Only "webhook" triggers exist today	Set trigger.triggerType to "webhook".
missing_connector	The connectorKey you used isn't a registered connector	Check the spelling, or browse available connectors.
missing_capability	That connector exists, but doesn't support the actionType you used	Check the connector's page for its actual action list.
missing_credential	The connector needs to be installed and active in your workspace first	Go install/connect it — see Connect Your First App — then re-validate.
schema_mismatch	A required input field for that action is missing	Fill in the field named in the error message.
duplicate_key	Two actions share the same key	Give each action a unique key.
orphan_node	The flow has zero actions	Add at least one action — a trigger with nothing to do isn't valid.
cycle	Reserved for future branching; not reachable in today's linear (single-path) flows	Nothing to do — this can't currently occur.

Worked example

curl -X POST https://api.snaplink.cloudsolutionaccelerators.com/api/v1/flow-designer/validate \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "workspaceId": "ws_92a1c4f0e7b3",
    "definition": {
      "trigger": { "key": "trigger", "connectorKey": "webhook", "triggerType": "webhook" },
      "actions": [
        { "key": "notify", "connectorKey": "slack", "actionType": "send_message", "input": {} },
        { "key": "notify", "connectorKey": "hubspot", "actionType": "create_contact", "input": { "properties": { "email": "lead@example.com" } } }
      ]
    }
  }'

Note the response envelope here — /flow-designer returns { "data": ... } with no "ok" field:

{ "data": {
  "valid": false,
  "errors": [
    { "code": "duplicate_key", "message": "Duplicate action key 'notify'.", "location": "notify" },
    { "code": "schema_mismatch", "message": "Missing required input 'channel' for 'send_message'.", "location": "notify" },
    { "code": "schema_mismatch", "message": "Missing required input 'text' for 'send_message'.", "location": "notify" },
    { "code": "missing_credential", "message": "Connector 'hubspot' is not installed/active for this workspace.", "location": "notify" }
  ]
} }

Reading this: two actions were accidentally both named "notify" (rename one), the Slack action is missing its required channel and text fields (fill them in), and HubSpot isn't connected in this workspace yet (install + connect it, then re-run validate). Fix each, re-validate, and once valid: true and errors is empty, you're clear to promote — see Creating Flows or Editing Flows.

Step-by-step

1. Write or edit your definition (directly, or via a draft's PUT /drafts/:id).
2. POST /flow-designer/validate with your workspaceId and definition.
3. Fix every error in the errors array, using the table above.
4. Re-validate until valid: true.
5. Promote.

Best practices

• Install and connect every required app before wiring its actions into a flow — it eliminates most missing_credential errors before they happen.
• Fill in every field marked required by the connector's action — most schema_mismatch errors are exactly this.
• Validation is a pre-flight check, not a guarantee — a valid flow can still fail at runtime (rate limits, the third-party app being down, a bad webhook payload). See Flow Debugging for that.

FAQ

Why "missing_credential" when I already installed the connector? It also needs to be active (fully connected/authorized) in this specific workspace, not just installed — see Connect Your First App. Does validation run automatically? Snap Studio's check step calls this under the hood; the raw API only validates when you explicitly call POST /flow-designer/validate.

If something goes wrong

If a flow validates cleanly but still won't run, see Flow not running.

---

Related: Creating Flows · Editing Flows · Flow Debugging