# Pagination and idempotency

> Page through Stacksync API lists, retry creates safely with an Idempotency-Key, and check a write with validate_only

Source: https://docs.stacksync.com/api-reference/pagination-and-idempotency

## Pagination

Lists take `limit` and `offset` query parameters and answer one envelope:

| Parameter | Values                   |
| --------- | ------------------------ |
| `limit`   | 1 to 200, default 50     |
| `offset`  | Items to skip, default 0 |

```json
{ "data": [], "has_more": true, "limit": 50, "offset": 0 }
```

While `has_more` is `true`, request the next page with `offset` + `limit`:

```bash
curl "https://api.stacksync.com/v1/workspaces/1234/queues?region=usnv&limit=50&offset=50" \
  -H "Authorization: Bearer $STACKSYNC_API_KEY"
```

The sync lists (syncs, sync triggers, sync webhooks and sync issues) predate this convention and page their own way: each one's page shows its parameters and answer.

## Idempotency

Create operations accept an `Idempotency-Key` header, so a retry after a timeout or a dropped connection never creates the resource twice:

```bash
curl -X POST "https://api.stacksync.com/v1/workspaces/1234/queues?region=usnv" \
  -H "Authorization: Bearer $STACKSYNC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2a1e-orders-queue" \
  -d '{ "queue_name": "Orders", "flush_batch_size": 100, "flush_record_max_age": 60 }'
```

* The key is 1 to 255 visible ASCII characters. A UUID per logical request works well.
* For 24 hours, a retry with the same key and the same request creates nothing and answers the first result again, with the header `Idempotent-Replayed: true`.
* The same key with a different request answers **422**.
* A retry while the first request is still running answers **409**: wait, then retry.

An operation accepts the header when its page lists `Idempotency-Key` under its header parameters.

## Validate a write

Write operations that list `validate_only` in their request body run every check of the write without writing anything. With `"validate_only": true`, a valid request answers **204** with no body, and an invalid one answers the error the write would. Use it to check a request before you send it for real. A few operations answer a check result instead of 204; their page shows it.