Error codes

The REST API and the MCP server 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.

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.
`IDEMPOTENCY_KEY_CONFLICT`	`409`	The same `idempotency_key` was reused with a different body. See Idempotency.
`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.
`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.

API errors: the envelope and status codes.
Conventions: what a malformed request gets.
MCP errors: the same codes on the MCP server.

Start

Conventions

Errors

Webhooks

Endpoints

Codes

Common causes of INVALID_INPUT

​Codes

​Common causes of INVALID_INPUT

​Related

Codes

Common causes of INVALID_INPUT

Related