# Limits

> Page sizes, backing off on 429 and 503, and how fresh the data is.

What the API bounds today, what it does not, and how fresh its data is.

## Page size

A collection returns 1 to 200 items per page. `limit` defaults to 50, and a larger value than 200 is capped at 200 rather than refused. Every page is bounded, so no single request reads a whole ledger. [Pagination](https://www.vestiarion.xyz/docs/get-started/pagination) covers the rest.

## Rate limits

Reads have no rate limit. Writes are limited to 30 a minute for each key, counted on each server instance, so a burst can now and then get a little past it. Over the limit, a write answers `429 rate_limited` with `Retry-After: 60`. No endpoint returns `503` today, but `unavailable` is a defined [error code](https://www.vestiarion.xyz/docs/get-started/errors): write your client to back off on both, and it keeps working if a limit is added to reads.

- On a `429`, wait at least as long as the `Retry-After` header says, in seconds, before you try again.
- On a `503`, retry with exponential backoff.

Poll no more often than you need to. To react to each new ledger entry, [webhooks](https://www.vestiarion.xyz/docs/webhooks) push it to you, so you do not need to poll the ledger quickly.

## Request bodies

A write's body is one JSON object of at most 64 KB. A body that is larger, is not JSON, or has a field the operation does not take answers `400 invalid_request`, and nothing is written. To make a retry safe, send an `Idempotency-Key`: [Retrying safely](https://www.vestiarion.xyz/docs/guides/api-invoices#retrying-safely) explains it. A payee link takes none: a repeat makes a new link, which replaces the first.

## Keys and endpoints per workspace

| Resource | Limit |
| --- | --- |
| Active API keys | 20 per workspace. Revoke one to create another. |
| Active webhook endpoints | 5 per workspace. |

## Freshness

Data is read live on each request: responses are not cached, so an invoice, a decision or a payment is visible on the next request after it is recorded.

Two endpoints report on the latest cycle rather than on this moment:

- [Treasury](https://www.vestiarion.xyz/docs/api/get-treasury)'s `obligations` come from the latest completed cycle snapshot, and are `null` until one exists.
- [Insights](https://www.vestiarion.xyz/docs/api/get-insights) reports the telemetry of recent cycles, transfers and screenings.

## Response shapes

Every endpoint answers with the documented envelope: `data`, plus `page` for a collection, or `error`. New fields can be added to v1 responses, so ignore fields you do not know rather than rejecting the response. A field is not removed from, or changed in, v1 without an entry in the [changelog](https://www.vestiarion.xyz/docs/changelog).