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 |
Quota 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 messages
| 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 messages
| 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.