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

# Failure Playbooks

> Error recovery strategies for common MCP tool failures.

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

<Info>
  These are **MCP tool** error codes. The REST v1 surface uses a different
  vocabulary (`validation_failed`, `unauthorized`, `forbidden`, `not_found`,
  `conflict`, `rate_limited`, `internal_error`) — see
  [Errors](/docs/api/errors) for that set and a condition-by-condition crosswalk.
  The two are not aliases; do not map one onto the other in client code.
</Info>

## 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`    | Caller cannot act on this record       | Check workspace membership 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**:

```json theme={"dark"}
{
  "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`:

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

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

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

***

## Workspace Errors

### `workspace_not_set`

**Cause**: No active workspace selected for this session.

**Example response**:

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

**Recovery**:

```json theme={"dark"}
// 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
```

<Info>
  Most tool calls require an active workspace. Call `workspace action=set` early
  in your session.
</Info>

***

## Entity Errors

### `entity_not_found`

**Cause**: The entity ID doesn't exist or you don't have access.

**Example response**:

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

**Recovery**:

```json theme={"dark"}
// 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**:

```json theme={"dark"}
{
  "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**:

```json theme={"dark"}
// 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
  }
}
```

<Warning>
  Using `force: true` skips hierarchy verification. Only use when you're sure
  incomplete children are acceptable.
</Warning>

### `stale_version`

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

**Example response**:

```json theme={"dark"}
{
  "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**:

1. Re-read the entity with `orgx_search` (with `id` parameter)
2. Apply your changes to the fresh data
3. Retry the update

***

## Agent Errors

### `spawn_blocked`

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

**Example response**:

```json theme={"dark"}
{
  "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**:

```json theme={"dark"}
// 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**: The accumulated cost of an autonomous session reached its
`max_cost_usd` limit, so no further work was dispatched.

**Example response**:

```json theme={"dark"}
{
  "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
    }
  }
}
```

Note the example: `actual_cost_usd` is **above** `max_cost_usd`. That is
expected, not a reporting bug. The cap is evaluated at accounting boundaries —
before dispatch against a priced estimate, and between work items against
accumulated cost — so a step already in flight when the line is crossed runs to
completion and bills in full. `max_cost_usd` bounds what gets *started*; it does
not truncate a step already running.

**Recovery**:

* Review the morning brief: `orgx_recommend`
* Start a new session with adjusted budget if needed
* Expect the final figure to land slightly over the cap when the crossing step
  was already running. The session closes with status `budget_exceeded` and the
  overage is raised as a `budget_breach` decision, so it is reviewable rather
  than silent
* Set `max_cost_usd` below the number you actually want to stay under, sized for
  the cost of one step

***

## Rate Limiting

### `429 Too Many Requests`

**Cause**: Exceeded rate limits.

**Example response**:

```json theme={"dark"}
{
  "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 caller is authenticated, but the account behind the connection
cannot act on this record — wrong workspace, or a role that does not permit the
action.

**Example response**:

```json theme={"dark"}
{
  "error": {
    "code": "permission_denied",
    "message": "Caller cannot act on this record in the active workspace.",
    "status": 403
  }
}
```

<Warning>
  Reconnecting with a broader scope set will not clear this. OAuth scopes are
  recorded at consent and reported back as `granted_scopes`; they are not
  compared against a call. Authorization comes from authentication plus
  workspace membership — see [Declared scopes](/docs/api/mcp-protocol#declared-scopes).
</Warning>

**Recovery**:

1. Confirm the active workspace holds the record: `workspace action=get`
2. Confirm the signed-in account is a member of that workspace
3. Check the trust level for the action with `get_my_trust_context`
4. Ask a workspace admin to add the account or elevate its role

***

## Validation Errors

### `400 invalid_input`

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

**Example response**:

```json theme={"dark"}
{
  "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**:

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

***

## Internal Errors

### `500 server_error`

**Cause**: An unexpected internal error occurred on the server.

**Example response**:

```json theme={"dark"}
{
  "error": {
    "code": "server_error",
    "message": "Internal server error. Please reference requestId when contacting support.",
    "status": 500,
    "requestId": "req_8f3a2b1c"
  }
}
```

**Recovery**:

1. Retry the request after a short delay (start with 1 second, use exponential backoff)
2. If the error persists after 3 retries, note the `requestId` from the response
3. Contact support with the `requestId` for investigation
4. Check the [Orgx status page](https://status.useorgx.com) for any ongoing incidents

***

## Connection Issues

### MCP connection refused

**Checklist**:

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

### Tools not appearing after config change

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

### Realtime voice connect fails

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

### Linear or billing actions fail

1. For Linear auth errors, reconnect Linear from **Settings → Integrations**
2. Retry the original action after the reconnect completes
3. 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` |

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Agent Quickstart" icon="rocket" href="/docs/agent-ops/agent-quickstart">
    Start from scratch with a working connection.
  </Card>

  <Card title="Tool Profiles" icon="users" href="/docs/agent-ops/tool-profiles">
    Reduce surface area and token usage.
  </Card>
</CardGroup>