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

> [!NOTE]
>
> 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](https://docs.useorgx.com/docs/api/errors.md) for that set and a condition-by-condition crosswalk.
> The two are not aliases; do not map one onto the other in client code.

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

***

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

> [!NOTE]
>
> 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**:

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

### `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](https://docs.useorgx.com/docs/api/mcp-protocol.md#declared-scopes).

**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

> [card] [Agent Quickstart](https://docs.useorgx.com/docs/agent-ops/agent-quickstart.md)
>
> Start from scratch with a working connection.

> [card] [Tool Profiles](https://docs.useorgx.com/docs/agent-ops/tool-profiles.md)
>
> Reduce surface area and token usage.


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