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

# Rate limits & quotas

> Request throttling, ISIN quotas, and the headers we return.

There are a few limits to be aware of: a per-minute **rate limit** on requests, a monthly **ISIN quota** for data retrieval, and a separate monthly **search ISIN quota**. All are determined by your subscription tier.

## Per-minute rate limit

Most requests count as one unit against a rolling 60-second window with the exception of `/api/v1/*_search` endpoints, which consume quota dynamically based on the `limit` and `full_reference_data` parameters. Your tier's exact limit is reported on every response in the `ratelimit` header, which is the source of truth.

### Response headers

We follow the [IETF draft v7 RateLimit header fields](https://datatracker.ietf.org/doc/draft-ietf-httpapi-ratelimit-headers/):

| Header             | Format                                | Meaning                                                                     |
| ------------------ | ------------------------------------- | --------------------------------------------------------------------------- |
| `ratelimit-policy` | `<limit>;w=<window-seconds>`          | The policy applied to your key.                                             |
| `ratelimit`        | `limit=<L>, remaining=<R>, reset=<T>` | Live state: `L` allowed in this window, `R` left, `T` seconds until reset.  |
| `retry-after`      | `<seconds>`                           | Set on `429` responses. Some HTTP clients use it to throttle automatically. |

Example:

```
ratelimit-policy: 100;w=60
ratelimit: limit=100, remaining=42, reset=23
```

### When you exceed the limit

You'll get `429 Too Many Requests` with `retry-after` set. The body uses the standard [error envelope](/errors):

```json theme={"theme":{"light":"catppuccin-latte","dark":"github-dark-high-contrast"}}
{
  "errors": [
    { "detail": "Too Many Requests" }
  ]
}
```

Wait until `reset` (or `retry-after`) has elapsed and retry. If the server is shedding load, you may also see `429` briefly while it recovers.

### Practical tips

* Read the `ratelimit` header and slow down before you hit zero.
* Batch ISINs into one call when you can. Every endpoint accepts a list.
* Add jitter to your retries to avoid thundering-herd patterns.

## Monthly ISIN quota

Your tier caps how many **distinct ISINs** you can pull reference, pricing, or cash flow data for in a billing month. After an ISIN counts against your quota in a given month, repeated requests for it that month are free.

<Tip>The `*_search` endpoints don't consume this data-retrieval ISIN quota — they're metered against a separate search ISIN quota. Use search to discover and filter before pulling reference or pricing data.</Tip>

### Tiers

Allowances, price-history windows, and resource access depend on your plan. Common tiers:

* **Startup**:
  * 3,000 ISINs returned / month on reference, pricing, cashflows and equivalent endpoints;
  * 10,000 ISINs returned / month on search endpoints;
  * 1-year price history.
* **Enterprise**: custom allowances and price-history windows.

## Response size limits

Each endpoint caps the number of items returned per response (typically 1,000, though higher response limits are available for enterprise users). If your request matches more, only the first page is returned. Narrow the filter or split the ISIN list to retrieve the rest.