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.
- What you'll do
- Find the symptom you are seeing, read why it happens, and apply the fix.
- What you'll have
- The specific change that clears the error, or the exact facts to send support if it does not.
Quick definitions: HMAC signature, x402, and EVM address
- HMAC signature
- A keyed hash computed with a shared secret. It proves a request came from someone holding the secret and was not altered on the way.
- x402
- An open payment protocol built on HTTP status 402 (Payment Required). The server answers an unpaid request with its price, the caller's wallet signs a payment and retries, and the work runs once the payment settles.
- EVM address
- A 0x-prefixed wallet address on Ethereum-compatible networks such as Base. Payouts settle to the address you set.
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 PAYMENT-SIGNATURE 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 in your workspace 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 per-run cap, $5 by default; a paid caller's run is also bounded by the amount reserved for it) 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 per-run cap (RUN_COST_CEILING_USDC) deliberately if you run your own deployment. The abort message says how many iterations completed.
A loop iteration fails with a nesting-depth error.
Why The engine's subflow depth guard caps subflow/loop nesting at 16 levels. Each Subflow or Loop node runs its inner flow one level deeper than the run that called it; a nested run that would cross the cap fails with a depth error, surfaced on that node (or that iteration) rather than the whole run.
Fix Flatten the design: hoist inner iterations upward, or restructure so a Transform prepares a flat list a single loop consumes. Sixteen levels is a guard against runaway recursion, not a budget to design toward.
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 exact limits are listed under Transform on the quick 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 Rotate it (POST /api/agents/<id>/webhook/rotate) to mint a new secret, 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.
Last updated .