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

# Error codes

> Every REST error code and its common causes.

The REST API and the [MCP server](https://docs.allocait.app/claude/errors.md) share one catalog of 19 codes. The table gives each code's meaning and its REST status; each operation under **Endpoints** in the API reference lists the ones it can return. For the envelope and the status codes, see [API errors](https://docs.allocait.app/api/errors.md).

## Codes

| Code | Status | Meaning |
| - | - | - |
| `INVALID_INPUT` | `400` | The request is malformed or breaks a rule it states. The message says which. See the common causes below. |
| `NOT_FOUND` | `404` | The path, id or name doesn't exist or isn't yours. For a name, `valid_values` lists the choices. |
| `ALREADY_EXISTS` | `409` | A create used a name that's already taken. Carries `existing_id`, plus `duplicate_ids` where older duplicates exist. |
| `IN_USE` | `409` | A delete was refused because something still uses the record. The message names it. Turning Allow shorts off while a short is held is refused the same way and carries `short_count` and `symbols`. |
| `CONFIRMATION_REQUIRED` | `409` | A list you sent would drop stored members. Carries `would_remove`; resend with those members in `remove`. |
| `PRICES_INCOMPLETE` | `400` | A price is missing. Carries `missing_symbols`. `/trades/check` needs a price for every held non-cash symbol and every changed symbol. A held option with a mark needs none. |
| `PRICES_INVALID` | `400` | A price is negative or isn't a number. 0 is a valid price for a holding. A changed symbol needs a price above 0. |
| `WOULD_CLOSE_POSITIONS` | None | MCP only, never returned by REST. A full holdings list left out holdings without closing them. REST's `/positions/apply` closes a holding you leave out instead. |
| `INSUFFICIENT_CASH` | `409` | A buy, a cover of a short or a withdrawal would overdraw cash. |
| `RULES_INVALID` | `400` | The rules text failed validation. Carries `issues`. |
| `TARGET_OUT_OF_BAND` | `400` | A rule's target is outside its own band. |
| `TIER_LIMIT_EXCEEDED` | `403` | An account limit was reached. Carries `limit_type`, `current_count` and `max_allowed`. |
| `FEATURE_NOT_AVAILABLE` | `403` | The account's agent access doesn't include playbooks, monitors, charts, webhooks or a key with **Read and change**. See [Access levels](https://docs.allocait.app/concepts/access-levels.md). |
| `IDEMPOTENCY_KEY_CONFLICT` | `409` | The same `idempotency_key` was reused with a different body. See [Idempotency](https://docs.allocait.app/api/idempotency.md). |
| `DAILY_LIMIT_EXCEEDED` | `429` | The account reached its cap on support requests or feedback reports in the last 24 hours (20 each by default). See [Rate limits](https://docs.allocait.app/api/rate-limits.md#per-route-caps). |
| `READ_ONLY_KEY` | `403` | The key can only read, or the account's agent access is read-only. REST sends it with `Write permission required` for a key, and with `This account's agent access is read-only.` for an account. |
| `OAUTH_WRITE_NOT_GRANTED` | None | MCP only, never returned by REST. The connected app can only read. |
| `TOOL_REMOVED` | None | MCP only, never returned by REST. A retired tool name. |
| `INTERNAL_ERROR` | `500` | An unexpected failure. Carries a `request_id`. |

`TIER_LIMIT_EXCEEDED` covers the portfolio and scenario limits and other account caps, such as 20 API keys, 20 webhook endpoints, 50 watchlists, 200 symbols on one watchlist and 50 custom symbols on one monitor. Its `error` text names no plan or price, and `limit_type`, `current_count` and `max_allowed` say which cap and how far. Don't retry it; remove something first.

## Common causes of INVALID\_INPUT

* A missing or malformed field, a field of the wrong type, an id that isn't a UUID, or a duplicate in a list.
* A change the target doesn't allow, such as a system class or Cash. For a CHOICE Input, the message lists the allowed options.
* On a holdings write, a negative `shares` on a portfolio with Allow shorts off or for an option holding (the refusal carries `symbols`), a `mark` on a holding that is not an option, or a trade worth 100000000000000 or more.
* On `/trades/check`, a trade in an option that has expired.
* On `/positions/size`, a `direction` other than `long` or `short`, or a negative `manual_shares` with `direction` `short`.
* On `/validate`, a negative `CASH` or `$CASH` entry (`allocations.CASH cannot be negative. Cash is never held below zero.`), or an `allocations` entry beyond plus or minus 1000000.

## Related

* [API errors](https://docs.allocait.app/api/errors.md): the envelope and status codes.
* [Conventions](https://docs.allocait.app/api/conventions.md): what a malformed request gets.
* [MCP errors](https://docs.allocait.app/claude/errors.md): the same codes on the MCP server.


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