# 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.