Reference
Errors & rate limits
Handle failures, request budgets and gradual polling.
JSON-RPC validation/unknown-method errors use MCP protocol error objects. Domain failures use isError=true and the structured error object. A response can be HTTP 200 while the MCP tool result is an error; inspect both layers. Authentication, missing scope, Origin, transport and middleware rate failures use HTTP status codes.
Common domain codes include invalid_arguments, validation_failed, not_found, insufficient_scope, forbidden, account_setup_required, integration_disabled, idempotency_conflict, rate_limited, internal_error and outcome_unknown. Errors include a request ID; quote it when asking for support. Do not log bearer tokens or full prompts in client telemetry.
| Budget | Limit per user per minute |
|---|---|
| Reads | 120 |
| Normal writes | 30 |
| AI/credit-generation actions | 5 |
| Publishing/approval-gated actions | 5 |
| Deletions | 3 |
Additionally the HTTP MCP endpoint is limited to 240 requests per IP per minute, OAuth routes to 60, registration to 10, and browser consent/settings to 30. The docs ZIP endpoint is limited to 5 downloads per minute. Use backoff and jitter; observe the returned retry_after detail or HTTP Retry-After header. Poll gradually (for example, 2 seconds initially then 5–10 seconds), not every animation frame. Every mutation, including validation failures, is bounded by the input schema; protocol bodies are limited to 256 KiB.
Limits are configured in config/caroush_mcp.php; shared cache/Redis makes them consistent across workers. The limiter is shared per user, not per freshly registered client, to discourage bypass by creating new clients.