> ## Documentation Index
> Fetch the complete documentation index at: https://docs.slaunt.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Slaunt MCP error reference

> Slaunt HTTP statuses, JSON-RPC codes, quota, scope, validation and Room error messages, and what to do about each.

Errors come in two layers. Transport and auth problems are HTTP status codes. Tool failures are HTTP `200` with a JSON-RPC `error` (`code`, `message`, sometimes `data`); `-32000` covers most of them, so the `message` is what tells you the cause.

## HTTP

| Status | Body | Cause | Fix |
| - | - | - | - |
| `400` | `-32600` `Mcp-Session-Id header is required after initialize` | Missing session header | Send it |
| `401` | `unauthorized` + `WWW-Authenticate` | Missing or expired token | Re-run OAuth |
| `403` | `insufficient_broker_scope` / `mcp_origin_not_allowed` | Token type or browser origin not allowed | Use a user token from an allowed client |
| `404` | `-32001` `Unknown MCP session` | Session expired or belongs to another token/client | Re-initialize |
| `404` | `MCP session terminated (<reason>)` | Session was ended | Re-initialize |
| `429` | `http_rate_limited` | Over 240 req/min | Wait `Retry-After` |

## JSON-RPC codes

| Code | Meaning | Retry? |
| - | - | - |
| `-32600` | Invalid request | No |
| `-32001` | Unknown session | After re-initializing |
| `-32602` | Bad params, invalid lifecycle transition, or thread routing conflict. `data` has details. | No |
| `-32009` | Lifecycle version conflict | Yes |
| `-32000` | Everything else; read `message` | Depends |

## Common `-32000` messages

**Quotas** fail closed: the request is refused, not queued. Show the message to the user; it already names the fix.

| Message | Cause |
| - | - |
| `Agent quota has been hit. To continue, disconnect an Agent from Slaunt or upgrade your plan.` | Too many concurrent agents |
| `<Quota> quota has been hit for the <Plan> plan...` | Monthly quota used up |
| `Unable to count active agents.` | Quota service briefly unavailable; retry |

**Scope and validation**

| Message | Cause |
| - | - |
| `org_id must be a valid UUID.` | You passed a scope argument; remove it |
| `thread_begin requires request_id` | Missing idempotency key |
| `event_id must be a valid UUID` | Malformed Context event ID |
| `actors must include at least one valid UUID.` | `actors` given without UUIDs; omit it to default to you |
| `Do not mix Codex session routing with another thread boundary` | Codex selector plus a generic boundary header |
| `Claude hooks require an authenticated Claude Code MCP runtime.` | Hook ran on a connection that isn't Claude Code's |

**Room**

| Message | Cause |
| - | - |
| `... requires authenticated access.` | No signed-in user |
| `Room item not found.` | Wrong ID or no access |
| `Room item is outside the authenticated workspace/project bucket.` | Item belongs to another scope |
| `Workspace-wide Room writes require an authenticated workspace administrator.` | Use `project_scope: "current"` or ask an admin |
| `Room upload receipt expired...` / `...already been used.` | Receipts are time-limited and single-use; prepare a new one |
| `parent_item_id must reference a folder` | Parent is a file or group |
| `Parent folder would create a Room hierarchy cycle.` | Moving a folder under its own child |
| `Moving existing Room items across buckets is not supported yet.` | Changing `project_scope` on an existing item |
| `room_item_content_get only supports file items.` | Called on a folder or group |

Some limits don't error at all: Context summaries are cut to 20 words, and tags are lowercased, de-duplicated and capped at 5.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.