> ## Documentation Index
> Fetch the complete documentation index at: https://shield.fi/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Pagination and errors

> Paginate Shield Swap API collections, interpret HTTP errors, and implement safe retries for long-running clients.

Collection endpoints use offset pagination. Error responses use the HTTP status code and a JSON object containing an `error` string.

## Pagination

Pass `limit` and `offset` as query parameters:

```bash theme={"languages":{"custom":["/languages/leo.tmLanguage.json"]}}
curl "https://api.swap.shield.fi/pools?limit=50&offset=0"
```

Pool listing accepts a page size from 1 through 100. Begin with offset `0`, advance the offset by the number of returned items, and stop when the response metadata or an empty page indicates completion.

Do not assume that an offset identifies a permanent snapshot. New indexed activity can change collection ordering while a bot paginates. For reconciliation jobs, record stable resource identifiers and tolerate duplicates between pages.

## Error shape

Errors use this general structure:

```json theme={"languages":{"custom":["/languages/leo.tmLanguage.json"]}}
{
  "error": "error description"
}
```

| Status | Meaning                                             | Client action                                        |
| ------ | --------------------------------------------------- | ---------------------------------------------------- |
| `400`  | Invalid parameters or request body                  | Correct the request before retrying                  |
| `401`  | Missing, invalid, or expired authentication         | Refresh the wallet session or replace the API token  |
| `403`  | The wallet lacks access or administrator permission | Do not retry without a permission change             |
| `404`  | Resource or route was not found                     | Verify identifiers or treat the route as unavailable |
| `429`  | Too many requests                                   | Wait and retry with backoff                          |
| `500`  | Server, dependency, or configuration failure        | Retry only transient requests with a bounded policy  |

## Retry policy

Retry network failures, `429`, and transient `5xx` responses with exponential backoff and jitter. Set both a request timeout and a maximum number of attempts.

Do not automatically retry non-idempotent write requests unless the endpoint provides an idempotency mechanism or the client can prove the previous attempt did not take effect.

## Large integers

Preserve token amounts, liquidity values, and other on-chain integers exactly. When a response represents an integer as a JSON string, parse it with an arbitrary-precision integer type such as JavaScript `BigInt` rather than `number`.