Limits and errors
An MCP request can fail at the connection, protocol, or tool level. Inspect the returned message and structured details before retrying; some failures require corrected input or a permission change.
Limits
| Limit | Behavior |
|---|---|
| Tool calls | Up to 600 tools/call requests per minute per token. |
| PDF generation | Up to 60 generate_document calls per minute per token, also counted in the general tool limit. |
| Paginated lists | Default 50 results, maximum 100 per page. Follow the returned next_cursor. |
| Templates across projects | Listing without project_id is capped at 500 templates. If truncated is true, list individual projects with pagination. |
| Image imports | Public PNG, JPEG, or WebP images, up to 10 MB; workspace asset storage limits also apply. |
| Draft preview links | Valid for about 15 minutes. Read the draft again for a fresh link. |
| PDF download links | Short-lived signed URLs. Read the document again for a fresh link. |
generate_document spends a generation credit when it creates a new document. Replaying an existing document with the same idempotency key does not spend another credit. Rate limits still apply to tool calls.
Authentication and permissions
HTTP 401 means the bearer token is missing, invalid, expired, or revoked. Check the Authorization header, replace an invalid API token, or sign in again through OAuth. The response includes a WWW-Authenticate: Bearer challenge with OAuth discovery information.
Missing tools or permission-denied calls usually mean your connection lacks the required scope. Compare your permissions with the scope-to-tool table, reconnect with the needed permissions, and refresh the client’s tool list.
Resource not found can mean the ID is wrong or the resource is outside your connection’s workspace or resource access. Check both before retrying.
HTTP 405 on a browser visit is expected for a plain GET to the MCP endpoint. Connect with a Streamable HTTP MCP client.
Tool errors
A tool failure is returned as an MCP result with isError: true. The result includes readable text and, where available, structuredContent with a code and details. A successful HTTP request alone does not mean the tool succeeded.
| Error or condition | What to do |
|---|---|
rate_limited | Wait for retry_after_seconds, then retry. Reduce polling frequency. |
invalid_document | Fix the listed field paths and messages using describe_schema. |
invalid_operation | Correct the reported operation. No operations in that edit call were saved. |
lock_version_conflict | Review the returned current draft, reapply your changes, and use its latest lock_version. |
| Template is not published | Publish a valid draft before generating, or choose a published template. |
| Draft has publish problems | Resolve problems, inspect the draft again, then publish. |
idempotency_key_in_flight | Wait briefly and retry the same generation with the same key. |
credits_exhausted, no_active_period, period_ended, subscription_not_entitled | Resolve workspace credits or subscription access. These errors are marked retryable: false. |
storage_limit_exceeded | Resolve the workspace’s asset storage limit before importing again. |
| Image fetch or format error | Use a reachable public image URL in a supported format and size. |
A draft with publishable: null has not passed the publish check. Retry the check later rather than treating an empty problems list as confirmation that it is ready.
Generation failures
A queued document can later fail. get_document returns status: "failed" with a failure containing a code and message. Explain that failure and correct its cause before starting another generation.
If the document is completed but pdf_url is unavailable, retry get_document; this can happen during a temporary storage problem. Do not start another generation just to obtain a download link.
Protocol errors
Malformed JSON, unknown JSON-RPC methods, invalid parameters, and unreadable resources use JSON-RPC error responses. Correct the request shape or resource URI. MCP clients normally handle initialization and protocol negotiation for you.
For tool failures, follow structured retryable and retry_after_seconds hints when present. For generation retries, keep the same nonempty idempotency key for the same intended document; authoring calls do not have this generation retry guarantee.
Return to Authentication, Generate a PDF, or Author a template.