Errors and pagination

These conventions apply across the public REST API. Endpoint-specific parameters are documented in the company, document and dataset guides.

Pagination

List and search responses may split their results into pages. limit controls the requested page size. If there are more results, the response includes next_cursor.

A cursor is a continuation value generated by Finbar. Treat it as opaque: copy the string exactly without decoding, editing or constructing it.

Make the first request without cursor.
Process the returned results.
If next_cursor is present, repeat the request with that value as cursor.
Stop when next_cursor is absent.

Keep the same search target, filters and dataset selections. For GET requests, put cursor in the query string; for POST searches and dataset queries, put it in the JSON body. When reading document chunks, replace start_index with cursor for subsequent pages.

Do not assume a short page is the last page; check next_cursor.

Error responses

API errors contain an error object with these fields:

Field	Meaning
`code`	Stable error identifier for application logic
`message`	Human-readable explanation; its wording can change
`request_id`	Identifies the request when contacting support; also returned as `X-Request-ID`
`issues`	Field-level details on validation errors, when present

Use code to choose how to handle an error. Keep an HTTP-status fallback for codes your application does not recognize.

HTTP status	Meaning	Action
`400`	Invalid request	Correct the fields, IDs or filters before retrying
`401`	Missing or invalid authentication	Obtain a new REST API token; check that it was issued for the REST API
`403`	Insufficient permission or account access	Check the token's scopes and the account's API access
`404`	Item missing or unavailable to your account	Check the ID and whether the data is available
`409` with `dataset_changed`	The published dataset changed	Repeat discovery and rebuild the query
`429`	Request limit reached	Wait for the number of seconds in the `Retry-After` header
`500`, `503`, `504`	Server failure, temporary unavailability or timeout	Retry data reads after a delay, increasing the delay if failures continue

Missing and inaccessible items both return 404; this response does not tell you which case applies. Repeatedly retrying the same 400, 403 or 404 request will not correct its cause.

Request limits and support

See usage and limits for shared allowances and usage reporting. For a persistent error, send the request ID, time and operation to Finbar support. Do not include access tokens or client secrets.

MCP tools use a different error format, described in MCP tools and workflows.