Errors and limits
The error body
Section titled “The error body”REST and MCP refuse a call with the same body. REST returns it with the HTTP status below; MCP returns it as the text of a tool result with isError: true.
{ "error": { "code": "validation_error", "message": "invalid input", "issues": [ { "path": "definition.steps.0.seconds", "message": "Too small: expected number to be >0" } ] }}code is stable: branch on it, not on message. Some codes add a field: issues for validation_error, delivery for approval_delivery_failed, and preview and confirmation for confirmation_invalid.
Two refusals do not reach a tool on MCP: unauthorized is an HTTP 401 before any tool runs, and internal_error is the JSON-RPC error -32603.
Error codes
Section titled “Error codes”Each code, its HTTP status, what it means, and what to do. Each action’s possible codes are listed with it in the API reference.
validation_error(400): The input is invalid.issuesgives each invalid field’s path and what is wrong. Fix the fields named and call again.unauthorized(401): The credential is missing, invalid, or revoked. Check theAuthorizationheader or sign in again.forbidden(403): The credential may not call this action: an API key on a session-only action, a role too low, or a session’s write from another origin. Use the credential the reference names under “Caller”.not_found(404): The thing named does not exist in your project or workspace. Check the ID. An ID from another project answersnot_foundtoo.conflict(409): The call contradicts what exists: a second project in a workspace, a replay with a different input, removing the last admin, aworkflows.upsertwhoseexpectedLatestVersionis not the latest version. Read the message; do not retry unchanged. For a workflow save, the body’slatestVersionis the latest version: read the workflow, reapply your change, and save again with it.confirmation_invalid(409): Theconfirmationtoken is expired, used for a different input, or not yours. The body has a freshpreviewandconfirmation. Show the fresh preview to the user and confirm again only if they agree.unsupported_media_type(415): A session’s write without a JSON body. Sendcontent-type: application/json.sender_not_verified(422): Afromdomain is not a verified sending domain of the workspace. Use a verified domain, or have it verified (Sending).no_approvers(422): The workspace has no approvers, so a sending workflow cannot be approved. Have the installation’s operator add approvers.workspace_limit_reached(422): You have created as many workspaces as allowed. Use an existing workspace.rate_limited(429): A limit below was reached. Wait and call again later.approval_delivery_failed(502): Not every approval link could be mailed.deliverycounts how many were. Preview and confirm the call again: it mails new links only to those who did not get one.internal_error(500): Something failed on the server. The message gives no detail. Retry with backoff. Actions that take anidempotencyKeyare safe to retry with the same key.
Limits
Section titled “Limits”| What | Limit |
|---|---|
| Workspaces a user can create | 3 by default (MAX_WORKSPACES_PER_USER on a self-hosted installation) |
| Projects per workspace | 1 |
| Customer ID | 1 to 256 characters |
| Customer email | up to 320 characters |
| Attribute key, value | key up to 128 characters; a string value up to 10,000 characters |
| Event name | up to 128 characters |
| Idempotency key | 1 to 256 characters |
| Workflow and step IDs | lowercase letters, digits, _ and -, up to 64 characters |
| Steps per workflow | 1 to 50 |
| Delay | 1 second to 365 days |
| Email subject, body | 998 and 100,000 characters |
messages.list |
up to 100 per call (50 by default), oldest first |
| Confirmation tokens | valid 15 minutes; 60 previews per project per hour by default |
| Approval links | valid 24 hours; 50 links per project per day by default |
| Sign-in codes | 6 digits, valid 5 minutes, 3 attempts |
The defaults are settings of a self-hosted installation: SEND_CONFIRMATION_TTL, SEND_CONFIRMATION_RATE_LIMIT, and SEND_APPROVAL_DAILY_LINK_CAP.
A general rate limit on API and MCP requests, plan limits on monthly emails, and request size limits are planned.
Retrying safely
Section titled “Retrying safely”customers.upsert,workflows.upsert, and the read actions are idempotent: repeat them freely.events.track,workspaces.create,projects.create, andapiKeys.createtake anidempotencyKey. Send one if you may retry: a replay with the same key creates nothing new. It returns the first result forevents.track,projects.create, and aworkspaces.createwith the same name;apiKeys.createanswersconflictand names the key it created, because the key itself cannot be shown again.- A confirmed
workflows.activaterepeated with the same token returns the first result. - A send whose provider answer was lost is never resent blindly (message states).