Failure Playbooks

When things go wrong, these playbooks help you recover quickly. Each entry includes the error, root cause, and exact recovery steps.

Error Taxonomy

HTTP Status	Error Code	Description	Recovery
400	`invalid_input`	Request validation failed	Check parameter types and required fields
401	`auth_required`	OAuth token expired or session invalid	Reconnect MCP server for fresh OAuth
403	`permission_denied`	Insufficient permissions for this action	Check scopes and trust level
404	`entity_not_found`	Entity doesn’t exist or no access	Search with `orgx_search`
409	`stale_version`	Concurrent modification conflict	Re-read entity and retry
422	`hierarchy_incomplete`	Parent has unfinished children	Complete or cancel children first
422	`spawn_blocked`	Trust or budget insufficient	Check with `get_my_trust_context`
422	`budget_exhausted`	Autonomous session hit cost limit	Review `orgx_recommend`
422	`workspace_not_set`	No active workspace	Call `workspace action=set`
429	`rate_limit_exceeded`	Too many requests	Wait for `X-RateLimit-Reset`
500	`server_error`	Internal server error	Retry with exponential backoff

Authentication Errors

`401 Unauthorized` / `auth_required`

Cause: OAuth token expired or session invalid. Example response:

{
  "error": {
    "code": "auth_required",
    "message": "OAuth token expired. Reconnect your MCP client to re-authorize.",
    "status": 401
  }
}

Recovery: Most MCP clients handle token refresh automatically. If you get a persistent 401:

Reconnect: Disconnect and reconnect the MCP server in your client
Re-authorize: Your browser will open for OAuth sign-in
Retry: The failed tool call should work after re-auth

If using OpenClaw, click Disconnect then re-pair from the dashboard.

OAuth tokens are refreshed transparently by your MCP client. Persistent 401s usually mean the refresh token has expired — just reconnect.

Workspace Errors

`workspace_not_set`

Cause: No active workspace selected for this session. Example response:

{
  "error": {
    "code": "workspace_not_set",
    "message": "No active workspace. Call workspace action=set before using this tool.",
    "status": 422
  }
}

Recovery:

// Step 1: List available workspaces
{ "tool": "workspace", "args": { "action": "list" } }

// Step 2: Set the workspace
{ "tool": "workspace", "args": { "action": "set", "workspace_id": "ws_..." } }

// Step 3: Retry original tool call

Most tool calls require an active workspace. Call workspace action=set early in your session.

Entity Errors

`entity_not_found`

Cause: The entity ID doesn’t exist or you don’t have access. Example response:

{
  "error": {
    "code": "entity_not_found",
    "message": "Entity 'init_abc123' not found or you do not have access.",
    "status": 404
  }
}

Recovery:

// Search for the entity by type
{
  "tool": "orgx_search",
  "args": { "type": "initiative", "status": "active", "limit": 20 }
}

Common causes:

Typo in entity ID
Entity was deleted or archived
Entity belongs to a different workspace

`hierarchy_incomplete`

Cause: Attempting to complete an entity with unfinished child work. Example response:

{
  "error": {
    "code": "hierarchy_incomplete",
    "message": "Cannot complete initiative 'init_abc123': 3 child workstreams are still in progress.",
    "status": 422,
    "details": {
      "incomplete_children": ["ws_001", "ws_002", "ws_003"]
    }
  }
}

Recovery:

// Step 1: Check what's blocking completion
{
  "tool": "orgx_act",
  "args": {
    "dry_run": true,
    "type": "initiative",
    "id": "init_..."
  }
}

// Step 2: If blockers exist, resolve them first
// - Complete or cancel child tasks/workstreams
// - Or force complete:
{
  "tool": "orgx_act",
  "args": {
    "type": "initiative",
    "id": "init_...",
    "action": "complete",
    "force": true
  }
}

Using force: true skips hierarchy verification. Only use when you’re sure incomplete children are acceptable.

`stale_version`

Cause: Another process modified the entity between your read and write. Example response:

{
  "error": {
    "code": "stale_version",
    "message": "Entity 'task_xyz' was modified by another process. Re-read and retry.",
    "status": 409,
    "details": {
      "current_version": 5,
      "your_version": 3
    }
  }
}

Recovery:

Re-read the entity with orgx_search (with id parameter)
Apply your changes to the fresh data
Retry the update

Agent Errors

`spawn_blocked`

Cause: Trust level insufficient for the requested action, or budget exhausted. Example response:

{
  "error": {
    "code": "spawn_blocked",
    "message": "Trust level 'supervised' is insufficient for autonomous spawn. Required: 'trusted'.",
    "status": 422,
    "details": {
      "current_trust": "supervised",
      "required_trust": "trusted"
    }
  }
}

Recovery:

// Check trust context
{
  "tool": "get_my_trust_context",
  "args": { "workspace_id": "ws_...", "agent_type": "engineering-agent" }
}

If trust is insufficient:

Escalate to a human for approval
Use orgx_spawn to understand what’s needed
Build trust by completing supervised tasks first

`budget_exhausted`

Cause: Autonomous session hit its max_cost_usd limit. Example response:

{
  "error": {
    "code": "budget_exhausted",
    "message": "Autonomous session exceeded max_cost_usd ($5.00). Session terminated.",
    "status": 422,
    "details": {
      "max_cost_usd": 5.0,
      "actual_cost_usd": 5.03
    }
  }
}

Recovery:

Review the morning brief: orgx_recommend
Start a new session with adjusted budget if needed
The hard stop is intentional — no overspend is possible

Rate Limiting

`429 Too Many Requests`

Cause: Exceeded rate limits. Example response:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded for write operations. Retry after 1700000060.",
    "status": 429,
    "details": {
      "limit": 30,
      "window": "1m",
      "reset_at": 1700000060
    }
  }
}

Operation Type	Limit	Window
Read operations	100 req	1 min
Write operations	30 req	1 min
Agent operations	10 req	1 min

Recovery: Check response headers:

X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1700000060

Wait until X-RateLimit-Reset timestamp, then retry. For batch operations, use batch_create_entities instead of multiple orgx_write calls.

Permission Errors

`403 permission_denied`

Cause: The authenticated user does not have the required scopes or role for this action. Example response:

{
  "error": {
    "code": "permission_denied",
    "message": "Insufficient permissions. Required scope: 'entities:write'.",
    "status": 403,
    "details": {
      "required_scope": "entities:write",
      "your_scopes": ["entities:read", "workspace:read"]
    }
  }
}

Recovery:

Check your current scopes via your MCP client or the get_my_trust_context tool
Disconnect and reconnect the MCP server, selecting broader scopes during OAuth
If using a tool profile, verify the profile grants the required permissions
Ask a workspace admin to elevate your role if needed

Validation Errors

`400 invalid_input`

Cause: Request validation failed due to missing or malformed fields. Example response:

{
  "error": {
    "code": "invalid_input",
    "message": "Validation failed: 2 errors.",
    "status": 400,
    "details": {
      "errors": [
        { "field": "title", "message": "Required field is missing." },
        {
          "field": "type",
          "message": "Must be one of: initiative, workstream, task."
        }
      ]
    }
  }
}

Recovery:

Read the details.errors array to identify which fields failed validation
Correct the parameter types and values — refer to the tool catalog for expected schemas
Ensure all required fields are present before retrying

Internal Errors

`500 server_error`

Cause: An unexpected internal error occurred on the server. Example response:

{
  "error": {
    "code": "server_error",
    "message": "Internal server error. Please reference request_id when contacting support.",
    "status": 500,
    "request_id": "req_8f3a2b1c"
  }
}

Recovery:

Retry the request after a short delay (start with 1 second, use exponential backoff)
If the error persists after 3 retries, note the request_id from the response
Contact support with the request_id for investigation
Check the Orgx status page for any ongoing incidents

Connection Issues

MCP connection refused

Checklist:

Verify the hosted MCP URL is https://mcp.useorgx.com/mcp for normal client setup
Use https://mcp.useorgx.com/sse only if your client explicitly asks for legacy SSE
Verify network access to mcp.useorgx.com
Reconnect to trigger fresh OAuth flow
Check that npx mcp-remote is installed and up to date

Tools not appearing after config change

Restart your IDE completely (not just reload)
Verify mcp.json has valid JSON syntax
Check that the args array is correctly formatted
If using a profile, verify the profile name: ?profile=memory or ?profile=commander

Realtime voice connect fails

Confirm the browser has microphone permission for useorgx.com
Start the connection from a user gesture, such as clicking Connect
Sign in to an OrgX workspace before retrying; the app uses short-lived realtime session credentials
If realtime remains unavailable, continue with text input and capture the request ID for support

Linear or billing actions fail

For Linear auth errors, reconnect Linear from Settings → Integrations
Retry the original action after the reconnect completes
For Stripe checkout or billing portal errors, retry once and contact support with the request ID if it persists

Quick Reference

Error Code	First Action	Tool to Use
`401`	Reconnect MCP	Reconnect MCP server
`workspace_not_set`	Set workspace	`workspace action=set`
`entity_not_found`	Search entities	`orgx_search`
`hierarchy_incomplete`	Check children	`orgx_act dry_run=true`
`spawn_blocked`	Check trust	`get_my_trust_context`
`429`	Wait + retry	Check `X-RateLimit-Reset`

Error Taxonomy

Authentication Errors

`401 Unauthorized` / `auth_required`

Workspace Errors

`workspace_not_set`

Entity Errors

`entity_not_found`

`hierarchy_incomplete`

`stale_version`

Agent Errors

`spawn_blocked`

`budget_exhausted`

Rate Limiting

`429 Too Many Requests`

Permission Errors

`403 permission_denied`

Validation Errors

`400 invalid_input`

Internal Errors

`500 server_error`

Connection Issues

MCP connection refused

Tools not appearing after config change

Realtime voice connect fails

Linear or billing actions fail

Quick Reference

Next Steps

Agent Quickstart

Tool Profiles

​Error Taxonomy

​Authentication Errors

​401 Unauthorized / auth_required

​Workspace Errors

​workspace_not_set

​Entity Errors

​entity_not_found

​hierarchy_incomplete

​stale_version

​Agent Errors

​spawn_blocked

​budget_exhausted

​Rate Limiting

​429 Too Many Requests

​Permission Errors

​403 permission_denied

​Validation Errors

​400 invalid_input

​Internal Errors

​500 server_error

​Connection Issues

​MCP connection refused

​Tools not appearing after config change

​Realtime voice connect fails

​Linear or billing actions fail

​Quick Reference

​Next Steps

Agent Quickstart

Tool Profiles

Error Taxonomy

Authentication Errors

`401 Unauthorized` / `auth_required`

Workspace Errors

`workspace_not_set`

Entity Errors

`entity_not_found`

`hierarchy_incomplete`

`stale_version`

Agent Errors

`spawn_blocked`

`budget_exhausted`

Rate Limiting

`429 Too Many Requests`

Permission Errors

`403 permission_denied`

Validation Errors

`400 invalid_input`

Internal Errors

`500 server_error`

Connection Issues

MCP connection refused

Tools not appearing after config change

Realtime voice connect fails

Linear or billing actions fail

Quick Reference

Next Steps