# Limits & usage

> The per-minute rate limit, the monthly quota, and the headers that report both.

Source: https://api.tailend.dev/docs/limits-and-usage

Two independent limits apply to every key. Both return `429`, told apart only by `error.code`:

| Limit | Scope | On refusal |
| --- | --- | --- |
| Rate limit | Per key, per minute | `429 rate_limited`, short `Retry-After` — wait it out and retry |
| Monthly quota | Per client, per UTC calendar month, across every key on the account | `429 quota_exceeded`, `Retry-After` points at the 1st of next month — don't retry sooner |

A request refused by either limit isn't billed and doesn't consume the allowance that refused it.

> **TODO (owner):** publish the per-minute limit and monthly allowance for each
> plan here. Until then, read them from the headers below: they are always
> authoritative for your key.

## Headers

- `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset`, and the equivalent `RateLimit-*` trio — the per-minute limit, on every response.
- `X-Quota-Limit` / `X-Quota-Remaining` / `X-Quota-Reset` — the monthly allowance, only on a plan that has one.
- `Retry-After` — seconds to wait, sent on both `429`s and on `503`.

See the [API reference](https://api.tailend.dev/docs/api.md) for the headers on each response.

## Access

Every endpoint and `include=` add-on shows its access requirement in the endpoint reference. `include=source` requires an entitled key: without one you get `403 include_not_permitted`, unless you add `include_mode=lenient` — see [Shaping responses](https://api.tailend.dev/docs/shaping-responses.md).

## What to do

- Branch on `error.code`, not on the `429` status alone — the two limits need different responses.
- Read `X-RateLimit-Remaining` before you burst a batch of requests, and back off before you hit zero rather than after.
- A `304` still counts as a request against both limits.