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 result pages, 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.

Webhook inbox polling keeps returning a cursor, including on empty pages. Continue immediately while has_more is true; otherwise wait before polling again with the saved cursor. See polling and recovery.

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`	Unknown route, or item missing or unavailable to your account	Check the method, path, ID and whether the data is available
`409`	Conflicting state or idempotency key	For `resource_changed`, fetch current state before retrying. For `idempotency_conflict`, reuse the original input or use a new key for a new operation
`410`	Retired endpoint or expired retained content	For `endpoint_retired`, see published datasets. For `dataset_result_expired`, use your saved dataset to start a new run. For `event_retention_gap`, reconcile missed work before starting a new webhook checkpoint
`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.