Usage and errors | Finbar Docs

Request limits

API and MCP requests share your account's allowances. Creating more credentials or connecting another assistant does not create a separate allowance. Company, document, market-data and dataset reads count toward the data request limits. Daily allowances reset at midnight UTC.

When a limit is reached, the API returns HTTP 429. Wait for the number of seconds in Retry-After before trying again. MCP tool errors provide the wait as retry_after_seconds.

View usage

Request a REST API token with the https://api.finbar.com/usage:read permission. Use it to read daily usage for a date range:

curl --fail-with-body --silent --show-error --get \
  'https://api.finbar.com/v1/usage' \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --data-urlencode 'start_date=2026-09-01' \
  --data-urlencode 'end_date=2026-09-07'

Both dates are included. A request can cover up to 92 days, and recent activity may take a short time to appear.

GET /v1/limits reports account credits and research-run limits. It does not report the number of data requests remaining today.

Handle a failed request

API errors contain an error object with a code, message and request_id. Use the code to decide what your application should do. Message text may change.

HTTP status	What to do
`400`	Check the required fields, IDs and filters. Correct the request before retrying.
`401`	Obtain a new access token. Check that it was issued for the REST API.
`403`	Check the token's permissions and your account's access.
`404`	The requested item is missing or unavailable to your account. Check the ID returned by search.
`409` with `dataset_changed`	Discover the dataset again and rebuild the query.
`429`	Wait for the retry delay.
`500`, `503` or `504`	Retry a read after a short delay, increasing the delay if failures continue.

For MCP sign-in problems, see Connect an AI assistant. For a persistent API error, send the request ID, time and operation to Finbar support. Do not include access tokens or client secrets.