Errors, retries and compatibility

API errors have an error object with code, message and optional field details. MCP tool failures return isError: true and the same error information in text and structured content. Transport/protocol failures remain MCP errors. Use the x-request-id response header when reporting API failures; never include the bearer token.

Situation	Recovery
`401 connection-required`	Check that the bearer token is present, unexpired and connected. Create a replacement from the site editor if needed.
`403 agent-scope` or `forbidden`	The current role or connection lacks permission. Explain the missing scope; do not switch to a more privileged identity automatically.
`400 invalid-input`	Correct the indicated field paths using the generated schema.
`400 invalid-display-settings`	Read current capabilities and use supported fields and values.
`409 revision-conflict`	Reread the current context and affected records, reconcile changes, then use a new key.
`409 idempotency-conflict`	The key was used for a different request. Keep keys unique per logical mutation.
`409 folder-not-empty`	Move contents deliberately before deleting an empty folder.
`429 rate-limit`	Respect `Retry-After` (normally 60 seconds); prefer batches.
`503 temporarily-unavailable` or lost response	Retry the identical request with the same key and revision, with bounded backoff. Check current state before issuing a changed mutation.

Batch guarantees

Up to 50 supported changes are validated and committed atomically.
A batch advances the saved draft revision once.
A dry run performs validation without saving and does not reserve IDs.
Last 100 batch receipts per site are retained. A matching replay returns the original created-ID map. An older retry still carries its old revision, so it fails rather than blindly duplicating edits.
Receipts are scoped to the user and connection. Rotating a token does not transfer its retry keys; inspect saved content before resuming an interrupted import through a new connection.
Publishing has its own idempotency keys and immutable release records.

Rate and size limits

Each connection allows 120 requests per minute, in addition to the API's shared gateway/IP limits. The gateway can also throttle bursts. JSON requests must fit within the platform's 4 MiB request envelope; content batches have a 1 MiB body limit. Prefer concise batches and paginated reads over loading an entire archive into the agent context.

Versioning

The HTTP operation API is under /v1/. MCP and HTTP use the same operations and validators. Read capabilities rather than hardcoding design options. New supported options may be added; do not assume unknown values are usable before the live server returns them. No deprecation timeline or compatibility SLA is promised here.

Report an issue

Record the operation name, safe request ID, error code and whether a mutation may have completed. Remove credentials and private school content. Keep your original batch key and revision in your local checkpoint until the result is resolved.