Symptom, cause, fix
Most failures in this product are guardrails doing their job with a specific error attached. This page maps the errors you'll actually see to what tripped them and what to change.
Launch is rejected
Launch fails with a structural error about the graph.
Why: The flow isn't fully wired: a node island is disconnected from the main path, or a required connection is missing. Launch validates structure before any writes, so nothing half-publishes.
Fix: Open the canvas and trace every node back to the trigger. Delete leftover experiment nodes or wire them in. The error message names what's disconnected.
Launch fails with an invalid cron message.
Why: The Schedule node's cron expression doesn't parse. The format is five fields, UTC.
Fix: Use a five-field expression like 0 9 * * * (daily at 09:00 UTC). The launch error includes the offending string; fix it in the Schedule node's config.
Launch returns 409.
Why: Either the graph contains a Connector Lab API Operation node (simulation-only; it can never back a live endpoint), or the flow uses a graph feature launch doesn't support yet.
Fix: Replace the API Operation node with an HTTP Request node configured for the real API, then relaunch.
Launch fails saying the payout address is invalid.
Why: The payoutAddress isn't a valid EVM address.
Fix: Provide a 0x-prefixed address you control, or omit the field and set it before enabling settlement.
Calls don't behave as expected
Every call returns 402, even after paying.
Why: The retry isn't carrying a valid payment: the X-PAYMENT header is missing, the authorization doesn't match the quoted amount or payTo, or verification failed on-chain. A rejected payment returns a fresh 402 with the reason appended to the error string.
Fix: Read the reason in the 402 body. Re-read the terms from the accepts array on each challenge rather than caching them (a relaunch can change the price), and make sure the wallet holds USDC on Base, not another network.
The endpoint returns 404 for an agent you know exists.
Why: Only live agents resolve. Unpublished, delisted, and draft agents intentionally return the same 404 as never-existed ones. It could also be an id/slug typo.
Fix: Confirm the agent appears in /api/catalog. If you own it, check its status under My flows and relaunch if needed.
Calls return 429.
Why: Per-IP rate limiting on the run endpoint: a burst of 10, refilling at 0.5 requests/second.
Fix: Honor the Retry-After header and add client-side pacing. For fan-out workloads, queue calls instead of firing them simultaneously from one IP.
A priced agent returns 503 "payouts not configured".
Why: The agent is live and priced, but its creator never set a payout address. The platform refuses to settle money into nowhere.
Fix: If it's your agent: set a payout address and relaunch. If it's someone else's: nothing to do on your side; call it in dry-run or wait.
You expected to be charged but got a free run.
Why: Dry-run resolution kicked in: you sent a dryRun signal, the agent hasn't enabled settlement, or platform settlement isn't live. The response's settled field tells you the truth about payment on every call.
Fix: Nothing is wrong. Treat settled: false as the free path; the same request settles for real once the agent is live and you omit the dry-run signal.
Runs fail or stop early
A run aborts naming the cost ceiling.
Why: The run hit its in-run spend ceiling (the minimum of the per-run cap, $5 by default, and the agent's remaining daily budget) before a cost-bearing node. Loops are the usual culprit: worst-case loop cost is N times the subflow cost.
Fix: Shrink the loop's input, cap maxIterations lower, trim expensive nodes from the subflow, or raise the agent's daily budget deliberately. The abort message says how many iterations completed.
A loop iteration fails with a nesting error.
Why: One level of subflow/loop nesting is the engine's hard limit. A loop's subflow cannot itself contain another loop or subflow node.
Fix: Flatten the design: hoist the inner iteration into the outer flow, or restructure so a Transform prepares a flat list the single loop consumes.
The Loop node reports success but some items are null.
Why: Working as designed: loops collect per-item errors instead of failing the batch. Failed items are null in result, with details in the errors output.
Fix: Consume the errors output; branch on its length if partial success shouldn't count as success for your flow.
An HTTP node fails instantly on an internal or localhost URL.
Why: The SSRF guard blocks requests to localhost, private ranges (RFC1918), link-local, CGNAT, and .local/.internal hostnames, after resolving the hostname, on every redirect hop.
Fix: Point the node at a publicly resolvable URL. For local development against your own service, expose it through a public tunnel.
A Transform expression is rejected before it runs.
Why: The expression exceeded a hard limit (source length, tokens, nesting depth, AST nodes, evaluation steps, or wall-clock budget), or used a denied identifier: __proto__, constructor, and prototype are blocked everywhere.
Fix: Split the work across two Transform nodes, reduce map() fan-out, or move heavy reshaping upstream. The limits table is on the main reference page.
Webhook deliveries are rejected
Every webhook POST returns 401.
Why: Signature verification failed. The same generic 401 covers a bad signature, a stale timestamp (more than 5 minutes off, either direction), and a nonexistent agent, deliberately, so responses can't be used to enumerate agents.
Fix: Sign HMAC-SHA256 over the exact string "<timestamp>.<raw body bytes>" with the secret from launch, send it as x-suede-webhook-signature (sha256=<hex>) plus x-suede-webhook-timestamp in Unix milliseconds, use content-type application/json, and stay under the 256 KB body cap. The worked signing example is on the main reference page.
You lost the webhook secret.
Why: The secret is shown exactly once at launch and stored only as a hash: it cannot be recovered, and relaunching deliberately does not rotate it.
Fix: Use the secret-rotation action on the agent to mint a new one, then update the third-party service that signs deliveries.
Escalate with the facts
If none of the above matches, grab the run id from the response (or the run dock), the exact status code and error body, and contact us. The status code table is the fastest way to classify a failing call before reporting it.