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

# MCP errors

> Find the error code you got and what to do about it.

Every tool on the Allocait MCP server returns errors in one format:

```text theme={null}
Error [CODE]: what happened. The next step.
```

The message is written for the agent and usually ends with the next step: a tool to call, or something to ask the user. What the agent tells the user is up to the agent. Every tool error carries one of the 19 codes below. The same codes come back from the [REST API](https://docs.allocait.app/api/errors.md), and ChatGPT and Codex get them too: see [ChatGPT errors](https://docs.allocait.app/chatgpt/errors.md).

## Find your code

| Code | Page |
| - | - |
| `INVALID_INPUT`, `NOT_FOUND`, `ALREADY_EXISTS`, `IN_USE`, `CONFIRMATION_REQUIRED` | [Record and price errors](https://docs.allocait.app/claude/errors/records-and-prices.md) |
| `PRICES_INCOMPLETE`, `PRICES_INVALID` | [Record and price errors](https://docs.allocait.app/claude/errors/records-and-prices.md) |
| `WOULD_CLOSE_POSITIONS`, `INSUFFICIENT_CASH`, `IDEMPOTENCY_KEY_CONFLICT` | [Holding and rule errors](https://docs.allocait.app/claude/errors/holdings-and-rules.md) |
| `RULES_INVALID`, `TARGET_OUT_OF_BAND` | [Holding and rule errors](https://docs.allocait.app/claude/errors/holdings-and-rules.md) |
| `TIER_LIMIT_EXCEEDED`, `FEATURE_NOT_AVAILABLE`, `DAILY_LIMIT_EXCEEDED` | [Access and limit errors](https://docs.allocait.app/claude/errors/access-and-limits.md) |
| `READ_ONLY_KEY`, `OAUTH_WRITE_NOT_GRANTED` | [Access and limit errors](https://docs.allocait.app/claude/errors/access-and-limits.md) |
| `ACCESS_CHECK_FAILED`, HTTP `429`, HTTP `401`, consent screen messages | [Access and limit errors](https://docs.allocait.app/claude/errors/access-and-limits.md) |
| `TOOL_REMOVED`, `INTERNAL_ERROR` | [Failures](https://docs.allocait.app/claude/errors/failures.md) |

`ACCESS_CHECK_FAILED` and the rate limit are not among the 19 tool error codes. They happen before a tool runs.

## Fields in the result

The tool result also carries structured fields that an agent can branch on:

| Field | When it's present |
| - | - |
| `error_code` | Always. One of the codes above. |
| `message` | Always. The same text as the error line. |
| `retryable` | Always. `true` only for `INTERNAL_ERROR`. |
| `missing` | The symbols or fields still needed. |
| `valid_values` | The names or options you can choose from. |
| `would_remove` | With `CONFIRMATION_REQUIRED`: what the call would drop, by field. |
| `short_count`, `symbols` | With `IN_USE` from `save_portfolio` turning Allow shorts off: how many shorts are held, and which (up to 20). With `INVALID_INPUT` from a holdings write that refuses a negative count, a `moves` other than 1 on an Options holding, or a `mark` on a holding outside Options: the holdings it refused. |
| `request_id` | Only with `INTERNAL_ERROR`: an id to quote when you report it. No other result carries one. |

## What to do in general

### If you're the agent

* Tell the user in plain words what went wrong; the `message` text is written for you.
* For `PRICES_INCOMPLETE`, ask the user for the prices of exactly the symbols named, or use a price source they trust, then call again. With neither, say there is no result. Don't guess at what's missing.
* For `CONFIRMATION_REQUIRED`, confirm with the user before you resend with `remove` or `confirm_name`.
* For `RULES_INVALID`, fix every issue listed before retrying: a partial fix still fails.
* For a rate limit, wait the `Retry-After` interval, then retry the same call.
* For `check_trades`, treat any error as no result: say so, and don't work out the answer by hand.
* For `INTERNAL_ERROR`, retry once. For a connected app's `401`, connect again. For `ACCESS_CHECK_FAILED`, retry.
* For anything else, treat it as a stop: don't retry the same call unchanged.
* Send `send_feedback` only when the user asks, and leave holdings and account data out of it.

### If you're the user

* If a call needs **Read and change** access, change it for an app in **Settings > Apps** or for an API key in **Settings > API keys**. If the result says "This account's agent access is read-only.", changing it doesn't help. See [Access levels](https://docs.allocait.app/concepts/access-levels.md).
* If a connected app stops working with a `401`, remove the Allocait connector in Claude and add it again.
* If a tool or its description behaves in a way these pages don't explain, ask Claude to report it with `send_feedback` and `topic: tools`. To report how a whole task went, ask for `topic: early_access`. See [Send feedback](https://docs.allocait.app/guides/send-feedback.md) and [Support](https://docs.allocait.app/support.md).

## Related

> [card] [REST API errors](https://docs.allocait.app/api/errors.md)
>
> The same codes over HTTP.

> [card] [MCP tools](https://docs.allocait.app/claude/tools.md)
>
> Every tool at a glance.


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