Errors & limits

A tool that fails returns the public API's error envelope unchanged, plus a hint written for the assistant. Most clients show it verbatim, so this page is for reading what the assistant reports back.

{
  "error": {
    "status": 409,
    "code": "VERSION_LOCKED",
    "message": "…",
    "holder": { "name": "Ana" },
    "expiresAt": "2026-09-09T20:05:00.000Z",
    "hint": "Ana has this open in the editor (lock expires …). Nothing was written. Retry after the lock expires, or ask them to close it.",
    "retryAfterSeconds": 240
  }
}

Codes

Code	Status	Meaning	What to do
API_TOKEN_REQUIRED	401	No Authorization: Bearer atk_… (or X-API-Key) header reached the server	Check the client config; the placeholder from Studio must be replaced with the full token
INVALID_API_TOKEN	401	The token is revoked, expired, or belongs to a different organization than the org in the URL	Create or regenerate a token; check the org id
FEATURE_DISABLED	403	AI assistants are not on the organization's plan (requiredPlan: "team")	Upgrade in Studio → Settings → Billing
TOKEN_SCOPE_READ_ONLY	403	A write was attempted with a read token	Create a read + write token
PROJECT_REQUIRED	400	The token is organization-wide and the call named no project; the error lists the choices	Tell the assistant the project, or narrow the token
TOKEN_PROJECT_MISMATCH	403	The token is narrowed to one project and the call named a different one	Use the token's project (the message names it), or use an organization-wide token
NOT_FOUND	404	The document type, document, taxonomy or term does not exist in the view being read	A read token cannot see drafts; check the slug and status
VALIDATION_ERROR	422	The payload was refused; fields names each problem (an unknown field slug, a missing required field, a term that does not exist)	Fix the named fields; nothing was written
SLUG_CONFLICT	409	The requested slug is taken in the project	Omit slug to derive a unique one, or choose another
VERSION_LOCKED	409	An editor has the document open; holder.name and expiresAt say who and until when	Retry after the lock expires, or ask them to close it
RATE_LIMITED	429	A rate limit was hit; retryAfterSeconds says how long to wait	Wait; do not retry in a loop
PLATFORM_READ_ONLY	503	The operator has paused writes platform-wide; reads still work; retryAfterSeconds says how long to wait	Keep reading; do not loop on writes — wait and retry the write once
PLATFORM_MAINTENANCE	503	The platform is down for maintenance; everything except public delivery reads is refused; retryAfterSeconds says how long to wait	Wait retryAfterSeconds, then retry; do not retry in a loop
DELIVERY_BLOCKED	403	Content delivery for the organization is blocked by the platform (abuse containment); nothing was read or written	Do not retry; the organization's owner is notified when a block is set and can contact support from Studio → Help
ACCOUNT_CLOSED	403	The organization has been closed	Do not retry; the token will not work again
BILLING_TERMINATED	402	The organization's subscription was terminated for non-payment	Do not retry until an owner settles the invoice in Studio → Settings → Billing
QUERY_FAILED	500	The API could not complete the read or write	Retry; if it persists, contact support with the time and tool name

Anything else is passed through from the API with its own status, code and message.

Reads that answer "not found"

The public surface never distinguishes "does not exist" from "not published" — that would let a read token discover draft work. A document that exists as a draft is NOT_FOUND to a read token and to any read with the default status: "published". Use status: "draft" with a read + write token to see it.

Rate limits

Three limits apply, each per token, each answering 429 with a Retry-After the server turns into retryAfterSeconds:

Limit	Applies to	Why
120 reads / minute	Every read tool	Keeps a chatty assistant from affecting site builds that share the token
60 writes / minute and 2,000 writes / day	Create, update, publish, unpublish, trash, upload	The daily cap stops a runaway agent loop
300 requests / minute to the MCP server	Every call, including initialize and tools/list	A backstop for the server itself

Reads and writes are separate buckets: a throttled write never blocks reads. The assistant's hint says to wait retryAfterSeconds and not to loop; if it keeps hitting the daily cap, that is the signal to look at what it is being asked to do.

Errors from the client itself

The client says…	Meaning
Server failed to start / exited	Claude Desktop could not launch the mcp-remote bridge — usually npx not on its PATH (fix)
Authentication required	The header never reached the server; the config is wrong or the token placeholder was not replaced
Resource not found (-32002)	A resource URI named a document type or document that does not exist in the published view
Parse error / payload too large	The client sent malformed or oversized JSON (limit 1 MB)