Skip to content

Errors and limits

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.

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. issues gives 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 the Authorization header 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 answers not_found too.
  • conflict (409): The call contradicts what exists: a second project in a workspace, a replay with a different input, removing the last admin, a workflows.upsert whose expectedLatestVersion is not the latest version. Read the message; do not retry unchanged. For a workflow save, the body’s latestVersion is the latest version: read the workflow, reapply your change, and save again with it.
  • confirmation_invalid (409): The confirmation token is expired, used for a different input, or not yours. The body has a fresh preview and confirmation. 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. Send content-type: application/json.
  • sender_not_verified (422): A from domain 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. delivery counts 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 an idempotencyKey are safe to retry with the same key.
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.

  • customers.upsert, workflows.upsert, and the read actions are idempotent: repeat them freely.
  • events.track, workspaces.create, projects.create, and apiKeys.create take an idempotencyKey. Send one if you may retry: a replay with the same key creates nothing new. It returns the first result for events.track, projects.create, and a workspaces.create with the same name; apiKeys.create answers conflict and names the key it created, because the key itself cannot be shown again.
  • A confirmed workflows.activate repeated with the same token returns the first result.
  • A send whose provider answer was lost is never resent blindly (message states).