Limits & errors

Per-token rate limit

Every token is rate-limited to 60 requests per minute. On the Scale tier the cap is 600 requests per minute, applied automatically to every token in the workspace.

Exceeding the rate limit returns HTTP 429 with a Retry-After header (seconds until the current minute resets) and a structured MCP error with code: "rate_limited". The Retry-After value is signed, so a proxy in your network cannot forge a shorter wait.

HTTP/1.1 429 Too Many Requests
Retry-After: 24

{
  "jsonrpc": "2.0",
  "id": 7,
  "error": {
    "code": "rate_limited",
    "message": "Rate limit reached for this token (60 requests/min). Retry after the current minute resets."
  }
}

Per-workspace daily cap

A second, cumulative cap counts all requests across every token in the workspace, per UTC day. It resets at midnight UTC. When it is reached, all further MCP requests that day return 429 with a clear message.

How BYOA reads are billed

Plain read calls debit nothing. BYOA reads are included in your plan up to the daily caps above: that is the whole billing story for reads. There is no per-call price, no bundled allowance to track, and no overage meter on reads.

Credits are charged only where real agent work happens. A tool that runs an internal model step to do its job (natural-language customer.search is the v1 example) debits credits as the step it is. A triggered playbook run (v1.5) debits through the run it creates, like any run. You see credits in the run trace and dollars at billing.

The error contract

Every MCP error is a structured JSON-RPC error with a stable code and a human-readable message. Handle these kinds:

Error messages may cite a docs URL on this site. The quickstart's troubleshooting section maps the ones you will meet most often to what to change.