Limits, retries & errors
Make retries predictable across REST and MCP without repeating side effects.
Limits
| Limit | Value |
|---|---|
| Admitted operations per workspace | 120 per rolling minute |
| Writes within that total | 20 per rolling minute |
| Request body | 512 KiB |
| Completed write replay window | At least 90 days |
REST and MCP share the limits. These are operational limits, not an additional billing schedule. REST rate-limit responses include Retry-After: 60.
Idempotency
Every write needs a key: Idempotency-Key in REST or idempotency_key in MCP. It must contain 8–80 letters, digits, underscores, or hyphens.
The workspace, operation, key, and normalized arguments identify one intended action. An identical retry replays the saved response, even across REST and MCP or different credentials for the same workspace. Replayed REST responses include Idempotency-Replayed: true.
Different arguments with the same key return idempotency_conflict. An action still pending returns operation_in_progress with a receipt ID. Inspect the site or preparation job before deciding on another action; a timeout can happen after an external side effect.
Business errors are also saved for replay. After fixing a failed prerequisite, use a new key for the newly authorized attempt. Do not use a new key merely to retry an uncertain network outcome.
Error handling
| HTTP status | Meaning | Next step |
|---|---|---|
400 | Invalid arguments or missing retry key | Correct the request |
401 | Missing, expired, invalid, or revoked credential | Reconnect or replace the key |
402 | Subscription required | Complete or repair billing |
403 | Missing scope, wrong workspace, or disallowed browser origin | Check the connection |
404 | Resource not found within the workspace | Check the ID |
409 | State, license, funding, or retry conflict | Read the error code and resolve the blocker |
413 | Body too large | Reduce the payload |
429 | Workspace quota reached | Wait before retrying |
5xx | Internal or provider failure | Inspect state before retrying a write |
MCP tool failures use isError: true with a structured error code. Authentication and protocol errors can occur before the tool runs.
Usage and tracing
REST responses include X-Request-Id; MCP operation results include request_id. Keep these IDs when investigating a failure.
get_usage counts admitted operations in the past 30 days, grouped by operation. It includes business failures; requests rejected before admission and replayed receipts do not create a new operation.