Errors

Every error is JSON with a human message and a stable machine code. When one query parameter is at fault, param names it:

{
  "error": "Unknown parameter `lmit`: /api/v1/companies does not take it and nothing was fetched. Did you mean `limit`? It takes `country`, `sector`, `search`, `scope`, `sort`, `direction`, `limit`, `offset`.",
  "code": "unknown_parameter",
  "param": "lmit",
  "allowed": ["country", "sector", "search", "scope", "sort", "direction", "limit", "offset"]
}

Status	Code	Meaning	Do
400	`unknown_parameter`	A query parameter the endpoint does not take (often a typo). `allowed` lists the ones it takes.	Fix the name. Nothing was fetched or metered.
400	`invalid_parameter`	A value outside the parameter’s type, allowed values or range (`limit=abc`, a `limit` above its maximum, a parameter given twice)	Fix the value; the message gives the allowed values or the maximum. An unknown accounting `basis` returns the company’s `accounting_bases[]` to choose from.
400	`missing_parameter`	A required parameter is absent	Add it.
401	`unauthenticated`	Key missing, revoked or malformed, or an expired session token. A key that does not resolve is refused on public endpoints too, never served as anonymous.	Supply a valid key, or send none for a public endpoint. Don’t retry in a loop.
402	`upgrade_required`	Pro-only surface	Upgrade, or tell your user.
403	`forbidden`	Not allowed for this caller	Don’t retry.
404	`not_found`	Unknown company, country, symbol, period or accession	Re-resolve via `/search`.
409	`key_limit`	Too many active keys	Revoke one first.
409	`conflict`	The request conflicts with the resource’s current state	Re-read, then retry.
415	`unsupported_media_type`	A filing package with nothing renderable (XBRL-only)	Read the facts through `/financials` and `/fact-source` instead.
429	`rate_limited`	Per-minute or per-day ceiling	Sleep `Retry-After` seconds.
429	`quota_exceeded`	Monthly quota spent	Wait for `resets_at`; the body carries `sales_email` for more volume.
503	`auth_unavailable`	Your key could not be checked (our key store is down); the key may be fine	Retry after `Retry-After`; don’t rotate the key.
503	`upstream_unavailable`	A source behind the endpoint is down	Retry with backoff.
5xx	`internal_error`	Server fault	Retry with backoff; report it if it persists.

An endpoint may add a more specific code of its own; treat a code you don’t know by its HTTP status. Message strings are for humans and may change; codes are the contract.

Parameters are checked before anything is counted

Requests made with an API key, an OAuth token or through the MCP server are checked against the endpoint’s parameters in the OpenAPI spec before they reach your plan. A parameter the endpoint does not list, a value of the wrong type, outside its allowed values or above its maximum, a parameter given twice, or a missing required one is refused with a 400 and one of the codes above. These 400s are not metered: they spend no per-minute, daily or monthly allowance and no prepaid credits. A limit above the maximum the spec states for it is refused, never silently lowered. An error the endpoint finds after that check (an unknown company, a period it does not hold) counts as a request like any other.

Getting started

Coverage

Data

Concepts

Guides

For AI agents

Parameters are checked before anything is counted

​Parameters are checked before anything is counted

Parameters are checked before anything is counted