Errors

Errors come back at one of two layers.

Protocol errors

Malformed requests, unknown methods, or auth failures return a standard JSON-RPC error response. These are handled by your MCP host, not your prompt. Examples: a missing or invalid bearer token (401, with a WWW-Authenticate header), a disallowed origin (403), or a missing MCP-Protocol-Version header.

Tool failures

When a tool runs but can't complete, it returns a normal tool result whose body carries a structured error:

{
  "status": "failed",
  "error": {
    "code": "workflow_not_published",
    "message": "Workflow ast_123 has no published version to run.",
    "retry_after": null,
    "support_id": "a1b2c3d4e5f6"
  }
}

code: a stable, machine-readable string (see the table below).
message: human-readable explanation, safe to show the user.
retry_after: seconds to wait, when the error is transient (e.g. rate limits).
support_id: the Sentry trace id for this call. Quote it when contacting support; it's how we find your exact request.

Tip

When you report a problem, include the support_id. We cross-reference it against the audit log to see precisely what happened, without you having to re-share your data.

Error codes by tool

Tool	Code	Meaning
`confirm_save`	`build_expired`	The preview is older than one hour; re-run `build_system`.
`confirm_save`	`already_saved`	This build was already saved (idempotent, safe).
`confirm_save`	`partial_save`	Some assets saved; `push_errors` lists the rest. Re-running is safe.
`trigger_workflow`	`workflow_not_found`	No workflow with that id.
`trigger_workflow`	`workflow_not_published`	The workflow is a draft; publish it first.
`trigger_workflow`	`workflow_failed`	The workflow ran but errored; see `result`.
`trigger_workflow`	`execution_timeout`	Exceeded the execution cap.
`send_via_integration`	`integration_not_connected`	The user hasn't connected this app; the error includes a `connect_url`.
`send_via_integration`	`operation_not_found`	Bad operation slug for that integration.
`send_via_integration`	`oauth_token_expired`	The connection needs re-authorizing in the web app.
`send_via_integration`	`provider_error`	The third-party API rejected the request.
`run_enrichment` / `check_enrichment`	`job_not_found`	Unknown or expired job id (jobs are kept 7 days).
any	`scope_denied`	The key lacks the scope this tool needs; see Authentication & scopes.
any	`rate_limited`	Per-key rate limit hit; honor `retry_after`. See Rate limits.

Cancellation

A dropped connection is not a cancellation. To intentionally stop an in-flight build, your host sends an MCP CancelledNotification (or you call abort_build). The server aborts the upstream work, records it, and closes the stream.