# Errors and pagination

Handle failed REST requests and retrieve results across multiple pages.

Source: <https://docs.finbar.com/api-mcp/errors>

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.

1. Make the first request without `cursor`.
2. Process the returned results.
3. If `next_cursor` is present, repeat the request with that value as `cursor`.
4. 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](https://docs.finbar.com/api-mcp/usage.md) for shared allowances and usage reporting.
For a persistent error, send the request ID, time and operation to
[Finbar support](https://docs.finbar.com/web/support.md). Do not include access tokens or client secrets.

MCP tools use a different error format, described in
[MCP tools and workflows](https://docs.finbar.com/api-mcp/mcp-tools.md#tool-errors).