---
title: "Errors in the Fincanva Open API"
description: "Every error code the Fincanva Open API and MCP server return, with its HTTP status and meaning, and the shape of a failed REST call and a failed MCP tool call."
canonical_url: "https://fincanva.com/developers/open-api/errors-in-the-fincanva-open-api"
last_updated: "2026-10-11"
md_url: "https://fincanva.com/developers/open-api/errors-in-the-fincanva-open-api.md"
---

# Errors in the Fincanva Open API

When an operation fails, REST and MCP report the same error code with the same details, and the code decides the HTTP status.

## What does a failed REST call return?

A JSON body with `status: false`, a `message`, the error `code` and a `details` object: `unlockedBy` when a higher plan would allow the call, `resetsAt` when an allowance will recharge, and `data` with anything specific to the code. The HTTP status is the code’s, from the table below. Once the caller is identified, the response also carries an `X-Request-Id` header.

## What does a failed MCP call return?

A tool result with `isError: true`, whose `structuredContent.error` carries the same `code`, `message` and details as the REST body.

## Which error codes can a Fincanva operation return?

Every code, its HTTP status and what it means:

- `invalid_input` — HTTP 422. The parameters do not match the operation's schema; `details` lists every problem with its field.
- `payload_too_large` — HTTP 413. The request body is larger than an operation accepts; `details.maxBytes` gives the limit. Nothing was run or charged.
- `result_too_large` — HTTP 422. The request was valid, but its result is larger than Fincanva keeps (`details.maxBytes`; `details.what` names the value). The run is refunded. Narrow it (fewer instruments, a shorter period, fewer steps) and run it again.
- `ambiguous` — HTTP 422. A name you gave matches several instruments; `details` lists the candidates, so choose one and call again.
- `not_resolved` — HTTP 422. A name you gave matches no [instrument](/glossary/instrument) Fincanva has.
- `insufficient_history` — HTTP 422. The instruments do not have enough history for the period or [lookback](/glossary/calculation-window) asked for.
- `unauthorized` — HTTP 401. The API key or access token is missing, expired or revoked.
- `plan_limit` — HTTP 403. Your plan does not include this operation or this setting; `unlockedBy` names the lowest plan that does.
- `toolset_disabled` — HTTP 403. The user's own settings for this connected app exclude the operation: its family is switched off, or the app is set to read-only and the operation creates or changes something in their library. `details` names the family, or the operation and `readOnly`. Nothing was run or charged; the user can change either in Fincanva's Settings, under Connected apps.
- `licence` — HTTP 403. Fincanva withheld the answer because the data it would release may not leave Fincanva through the API or MCP: a provider's terms forbid it, or it is data Fincanva protects, such as its long-run price history or historical [index membership](/glossary/index-lists-and-point-in-time-constituents), which is never returned as rows. `message` says what was withheld and what is available instead, such as summary statistics or monthly figures computed over it; `details` names the dataset, its licence class and the channel.
- `quota_exhausted` — HTTP 429. This month's allowance of calls, heavy runs or research reports is used up; `resetsAt` gives the date it resets.
- `rate_limited` — HTTP 429. Too many calls in the current minute: this connection, or this account across its connections, reached its plan's per-minute limit. `resetsAt` gives the instant the minute recharges, and REST also sends a `Retry-After` header in seconds. Wait until then and repeat the call; nothing was run or charged. When a higher plan allows more calls a minute, `unlockedBy` names the next one that does.
- `not_found` — HTTP 404. The operation, or an item you named such as a filter, does not exist.
- `conflict` — HTTP 409. The item changed after the call you are following up was made, such as a saved item edited since its replace proposal was issued; nothing was written. Read the item again and repeat the edit.
- `busy` — HTTP 503. Fincanva is at capacity for this kind of run; nothing was charged against your allowance, so try again shortly.
- `engine_failed` — HTTP 502. The computation failed on Fincanva's side; nothing was charged against your allowance.
- `internal` — HTTP 500. An unexpected error on Fincanva's side; nothing was charged against your allowance.

Fincanva is for education and illustration only. It is not personalised financial advice, and past or simulated results do not predict future ones. [Read the Terms Addendum](https://fincanva.com/terms/addendum#section-3)