Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.chatblocks.ai/llms.txt

Use this file to discover all available pages before exploring further.

The MCP route follows the JSON-RPC spec for errors and maps a few categories onto HTTP statuses. This page is the reference for what each error means and what your agent (or client) should do about it.

​
Error codes

CodeMeaningWhen
-32001AuthMissing/invalid Authorization header or the cb_live_* key was revoked.
-32002Rate-limitPer-key sliding-window cap exceeded.
-32602Invalid paramsTool arg shape didn’t match the JSON Schema.
-32004Not foundTool name unknown, or the requested resource doesn’t exist in this workspace.
-32603InternalCatch-all server error. Also used for plan-gated tool calls — the message body contains PRO_REQUIRED.

​
HTTP status mapping

SituationHTTP statusBody shape
Auth failure401JSON-RPC error envelope
Rate-limit429JSON-RPC error envelope, includes a friendly retry hint
Any tool-level error200JSON-RPC error in the body (per MCP spec)
Healthy response200JSON-RPC result
The spec calls for tool errors to come back as 200 with the error inside the JSON-RPC envelope — clients that conflate HTTP status with “did the call succeed?” will misread these. The MCP SDKs all do the right thing.

​
Plan-gated tools

Some tools are Builder-only. On a Free workspace they return -32603 with a PRO_REQUIRED message that names the gated feature and (where applicable) suggests a Free alternative. The full list lives in the tool reference — look for the Builder plan required annotation in each tool’s description. Highlights as of v1.4:
  • blocks.create — AI block generator. Free alternative: hand-author via blocks.init + setFiles + build + publish.
  • schedule.set, schedule.pause, schedule.resume, schedule.delete, schedule.preview, schedule.runNow — entire scheduled-run surface is Builder-only.
  • dataSources.add with type=mcp outbound MCP creates beyond the per-type cap (Free is 1).
Coding agents: tool descriptions ending in (Builder plan required.) are gated server-side. Skip these on Free workspaces — call workspace.get first to read plan and limits, and reroute via the free alternative the description names.

​
Rate limits

Per-key sliding-window via @convex-dev/rate-limiter. The cap is resolved from workspace.plan at request time:
PlanRequests per minute (per key)
Free60
Builder600
Enterprise6000
Different keys for the same workspace get independent budgets — minting a second key buys you another 60/600/6000 RPM. The platform doesn’t penalize per-workspace, just per-key. When you hit the cap, the next call returns -32002 with HTTP 429 and a hint that includes the resume-time. Back off by ~60 / RPM seconds and retry.

​
Periodic limits

Two limits are time-windowed rather than rate-limited:
LimitFreeBuilderEnterpriseReset
Builds per month1001,000100,000First of next month UTC
AI-generated blocks per month03010,000First of next month UTC
Builds count every call to blocks.build (success or failure). AI-generated blocks count every blocks.create invocation. When you hit either, the next call returns -32603 with a LIMIT_REACHED message. Both limits expose resetsAt on the workspace.get limits payload, so agents can preflight.

​
Per-resource count caps

Create-time caps for workspace-owned resources. Hitting any of these returns LIMIT_REACHED from the relevant tool:
ResourceFreeBuilderEnterprise
Blocks1010010,000
Canvases2201,000
Scheduled runs15500
Data sources (per type)110100
BYOK keys0350
Workspace members1unlimitedunlimited
See Plans and limits for the full table.

​
Preflight via workspace.get

The cheapest way to avoid a 4xx is to read limits first. workspace.get returns: 
{
  "id": "...",
  "name": "...",
  "plan": "free",
  "limits": {
    "blocks": { "used": 7, "max": 10, "resetsAt": null },
    "buildsPerMonth": { "used": null, "max": 100, "resetsAt": "2026-06-01T00:00:00Z" },
    "members": { "used": 1, "max": null, "resetsAt": null }
  }
}
  • max: null means Infinity (members on Builder/Enterprise).
  • used: null on periodic limits means the rate-limiter doesn’t expose current consumption — only the cap.
  • resetsAt: null on count-based limits means there’s no time-based reset.

​
What’s next

Setup

Per-client configs for connecting Claude / Codex / Cursor / Windsurf.

Tool reference

Auto-generated list of every tool, with arg shapes and plan gates.