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

# Errors

> One error shape for every call, every code, and what to do next.

Every error has the same JSON body. `doc_url` in each error links to its code's row in the table below.

```json theme={null}
{ "error": { "code": "invalid_policy", "message": "Input should be a valid number, unable to parse string as a number",
             "param": "policy.tracking_error",
             "errors": [ { "field": "policy.tracking_error", "message": "Input should be a valid number, unable to parse string as a number" },
                         { "field": "policy.tracking_error", "message": "Input should be 'tight', 'moderate' or 'loose'" } ],
             "doc_url": "https://docs.abacuslabs.ai/errors#invalid-policy", "request_id": "req_8ab2d4e9ce79", "http_status": 422 },
  "credits_charged": 0 }
```

That came from `POST /v1/proposals` with `"policy": {"goal": "harvest_losses", "tracking_error": "abc"}`.

| Field | Meaning |
| - | - |
| `code` | Stable. Branch on it. (`type` repeats it, for older clients.) |
| `message` | What went wrong, in plain words. Do not parse it. |
| `param` | The request field at fault, when there is one. (`field` repeats it, for older clients.) |
| `next` | When present: what to do. |
| `doc_url` | A link to this code's row on this page. |
| `errors` | For `invalid_request` and `invalid_policy`: every field at fault. |
| `http_status` | The HTTP status, repeated in the body. |
| other fields | Details for some codes, such as `price` on `max_credits_exceeded`, `commit_id` on `option_already_committed`, `accounts` on `account_id_required`. |
| `request_id` | Quote it when you report a problem. `null` over MCP. |

Errors are free: they cost no credits.

These are answers, not errors: a proposal with `outcome: "infeasible"` or `"clarify"` (HTTP `201`), and a trade check with `status: "rejected"` (HTTP `200`).

## Codes

| HTTP | `code` | Why | What to do |
| - | - | - | - |
| 400 | `idempotency_key_required` | `POST /v1/commits` without an `Idempotency-Key` header. | Send one, such as a UUID. |
| 400 | `unsupported_api_version` | `Abacus-Version` is not a released version date (or is in the future). | Send `2026-11-15`, or leave the header out. |
| 401 | `unauthorized` | Missing, unknown or revoked key. | Send `Authorization: Bearer <key>`. Get a key with `POST /v1/keys`. |
| 402 | `credits_exhausted` | Not enough credits this month, or a spend cap is reached. | See [Credits](https://docs.abacuslabs.ai/credits.md#the-402-errors). |
| 402 | `max_credits_exceeded` | The call costs more than `max_credits`. | Raise `max_credits` or lower `effort`. |
| 402 | `portfolio_limit_reached` | A new account would pass the plan's portfolio limit. | Use an account already counted, or upgrade. |
| 403 | `forbidden` | The key lacks the scope for this call. | Use a key with `read`, `propose` and `commit`. |
| 404 | `not_found` | Unknown account, proposal, option or commit for this key. | Check the id. Ids belong to the key's organisation. |
| 404 | `snapshot_not_found` | Unknown or expired `snapshot_id`. | Send the account again. |
| 404 | `not_available` | The route is not part of the public API. | Use the calls in the [API reference](https://docs.abacuslabs.ai/introduction.md#the-six-calls). |
| 405 | `method_not_allowed` | The path exists, but not with this HTTP method. | Check the method in the [API reference](https://docs.abacuslabs.ai/introduction.md#the-six-calls). |
| 409 | `stale_snapshot` | Commit: the holdings changed since the option was made. | Show `replacement_option_id` to the person, then commit it. Or propose again. |
| 409 | `prices_moved` | Commit: a traded price moved more than 1%. | Same as above. |
| 409 | `option_already_committed` | Commit: this option was already committed with another `Idempotency-Key`. | `GET /v1/commits/{commit_id}` (in the error). |
| 409 | `idempotency_conflict` | Commit: this `Idempotency-Key` was used with a different body. | Use a new key for a new request. |
| 409 | `idempotency_key_reused` | A paid call: this `Idempotency-Key` was used with a different route or body in the last 24 hours. | Use a new key for a new request. |
| 409 | `idempotency_in_progress` | A paid call: the first request with this key is still running. | Retry after `Retry-After` seconds; you get its answer. |
| 409 | `reference_conflict` | Commit: `reference` is already used by another commit. | Use a new `reference`. |
| 409 | `rules_failed` | Commit: the option no longer passes the rules at today's prices. | Propose again. |
| 409 | `resolve_failed` | Commit with `on_stale: "resolve"`: the option is stale and could not be re-solved. | Propose again. |
| 409 | `overfill`, `fill_exceeds_position` | Commit: a fill is larger than the trade or the holding. | Send the fills as the broker reported them. |
| 410 | `option_expired` | Commit: the option is older than 15 minutes. | Show `replacement_option_id` to the person, or propose again. |
| 413 | `payload_too_large` | The request body is above 2 MB. | Save the account once (`POST /v1/accounts`) and send `account_id`. |
| 422 | `invalid_request` | A field is missing or wrong. `param` names it. | Fix the field. |
| 422 | `invalid_policy` | A policy field is wrong or unknown. `param` names it. | See [The policy](https://docs.abacuslabs.ai/concepts/policy.md). |
| 422 | `invalid_benchmark` | Abacus Labs could not read the benchmark. | Use a ticker, an index name or a [benchmark object](https://docs.abacuslabs.ai/concepts/policy.md#benchmark). |
| 422 | `account_id_required` | Several accounts were sent to a proposal or check without `account_id`. | Say which account to trade in. `accounts` in the error lists them. |
| 422 | `duplicate_account` | The same account id was sent twice. | Send each account once. |
| 422 | `unsupported` | The request needs something Abacus Labs cannot do. | The message says what. Add a `goal` in plain English, or change the policy. |
| 429 | `rate_limited` | Too many calls today for this key, or too many new keys from this address. | Wait until 00:00 UTC, or use a live key. |
| 500 | `internal_error` | A fault on our side. | Retry once. If it repeats, report the `request_id`. |
| 503 | `llm_unavailable` | Analyze needs a language model and none answered. | Retry later. |

## Idempotency

`POST /v1/analyze`, `/v1/proposals`, `/v1/trades/check` and `/v1/accounts` accept an optional `Idempotency-Key` header (MCP: the `idempotency_key` argument). Send a new UUID per request and the same one on a retry:

* Same key and body within 24 hours: the first answer comes back with the same status and body, the header `Idempotent-Replayed: true` and `Abacus-Credits-Charged: 0`. Nothing is charged again.
* Same key, different body or route: `409 idempotency_key_reused`.
* Same key while the first request still runs: `409 idempotency_in_progress`.
* Only `2xx` answers are kept. After an error the key is free again, so fix the cause and retry with the same key.

`POST /v1/commits` always needs a key (see `idempotency_conflict` above).

## Versioning

`v1` is frozen. Send `Abacus-Version: 2026-11-15` to pin it; every response has `Abacus-Version` with the version used (the current one when you send none). Later changes get a new date; a pinned date keeps its behaviour.

## Proposals that fail in the background

A proposal that answered `202` and then failed has `status: "failed"` and the same `error` object on `GET /v1/proposals/{id}`. It costs nothing.

## Over MCP

An API error is a tool result with `isError: true` whose text is the same JSON. The text starts with `Error executing tool <name>: `. See [MCP server](https://docs.abacuslabs.ai/mcp-server.md#tools).


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