Errors in the Fincanva Open API

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 Fincanva has.
• insufficient_history — HTTP 422. The instruments do not have enough history for the period or lookback 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, 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.