Concepts

Errors

Every status the API returns, the JSON shape of an error, how MCP reports the same failures and when to retry.

When a REST call fails, the response has an HTTP status and a JSON body with one field, detail: a sentence that says what went wrong and, where it helps, what would work instead.

404 Not Found
{"detail": "Unknown ticker: APPL. Use search_companies to find the symbol."}

The message is written to be read by a person or passed straight back to an assistant, which can usually fix its own call from it. Match on the status code in code, not on the wording.

Status codesLink to this section

StatusMeaningExample detailWhat to do
400A parameter is missing, has the wrong type or is out of range, or a metric key is unknownInvalid parameters: years: Input should be less than or equal to 20Fix the parameter. For a metric, the message suggests close matches and lists the valid keys.
401No credential, an unknown or revoked key, or an expired access tokenMissing API key: send Authorization: Bearer fdz_live_...Check the header and the key; create a new key if it was revoked. Connected apps refresh their token and retry on their own.
402The account has no active plan or trial, or (once credits are enforced) no credits leftA Fundalyze subscription or active trial is required for this data.Start or renew a plan; see Credits.
404Unknown ticker, series or tool, no data for that request, or a data source that is switched offUnknown tool 'get_prices'. Available: search_companies, get_company, ...Check the name; for a ticker, try search_companies.
429Today's quota is used, or another call with the same credential is still runningAnother call with this API key is still running; ...If busy, retry when the running call ends; if the quota is used, wait until 00:00 UTC. See Limits.
503The API is temporarily switched off, or the data is not loaded yetThe Fundalyze API is temporarily switched offRetry later.
500, 502, 504Something failed on our side or on the way(may not be JSON)Retry with a growing delay; tell us if it persists.

Every call that fails is free: only successful calls count toward the daily quota.

Other messages you may seeLink to this section

Statusdetail
400Unknown metric 'revenues'. Did you mean: revenue? Valid for income: revenue, cost_of_revenue, ...
401Invalid API key
401This API key has been revoked
401Invalid or expired access token
402Out of credits. Buy a credit pack from Account -> Billing, or wait for your monthly credits. (only when credits are enforced)
404No annual income figures for XYZ in the normalized statements (funds and blank-check companies are not covered).
429This API key has used today's 2000 calls. The quota resets at 00:00 UTC (2026-10-08 00:00 UTC).

Errors over MCPLink to this section

The MCP server reports the same failures in the two ways MCP allows:

  • Before a tool runs, at the HTTP level: a missing, unknown or expired credential gets 401 with a WWW-Authenticate header that points the client at the sign-in metadata, so a connector can sign in again. A lapsed plan (402) and a switched-off API (503) come back with that status and the same {"detail": "..."} body as REST.
  • When a tool runs, as a tool result marked as an error (isError: true) whose text is the message: an unknown ticker or metric, a used-up quota, a busy credential, or a data source that is switched off right now ("This data source is switched off right now. Try again later."). The assistant reads the message and can correct the call or tell you.

Arguments that do not fit a tool's schema are rejected by the MCP layer with its own validation message before the tool runs.

RetryingLink to this section

  • Retry 429 (busy) after a short wait, and 5xx or network failures with a growing delay (for example 1, 2 and 4 seconds).
  • Do not retry 429 (quota used) before 00:00 UTC, or any other 4xx without changing the call: the answer will be the same.
  • Calls only read data, so a retry never does anything twice.

This page as Markdown, for language models and scripts: /developers/md/concepts/errors