# Allowances and rate limits

> The monthly allowances an account has, the per-minute limits on each kind of key, and what a refusal looks like.

Two kinds of limit apply. The monthly allowances are what a plan includes; the
rate limits stop a burst, and say nothing about a month.

## The monthly allowances

| Allowance | Each month | More |
|---|---|---|
| API requests | 250,000 | 25,000 more for USD 1.00 |
| Web analytics events | 10,000 | 50,000 more for USD 5.00 |

Both belong to the account rather than to one website, and both start again on
the first of each month, in UTC. They are counted apart: running out of
analytics events never stops the API a website reads from.

A request the allowance turns away is not counted, so a retry loop against a
`429` does not spend more of the month. Nor is anything refused before the API
looks at it: a key that is not valid or not the right kind, a website not on
the key's list, a part that is switched off, or a browser's preflight. Anything
answered after that counts, a booking refused with `slot_unavailable` included.
A crawler never spends an analytics event.

## Rate limits

| Calls | Limit | Counted per |
|---|---|---|
| Reads with a publishable key | `300/min` | visitor address and key |
| Writes with a publishable key | `10/min` and `30/hour` | visitor address |
| Any call with a secret key | `600/min` | key |
| Calls with a key that is not valid | `30/min` | address |

A publishable key is in a web page, so its limits follow the visitor rather
than the key: one visitor cannot spend a website's whole allowance, and writes
sprayed across many websites' keys cost as much as writes against one. An IPv6
address is counted by its /64, the block one connection is given, so walking
through it is still one visitor.

## When a limit is reached

Both answer `429`, in the usual [error shape](/docs/errors/), with the
type `rate_limit` and one of two codes.

| Code | Means | What to do |
|---|---|---|
| `throttled` | Too many calls in a short time | Wait the seconds in `Retry-After`, then send the same request again |
| `quota_exhausted` | The month's allowance is used up | Add more from the billing screen, or wait for the first of the month |

## Other limits

A project can hold 25 keys in use at once. A website can have
up to 4 webhook endpoints, and is sent at most 5,000 deliveries an hour.
A write with an `Idempotency-Key` is remembered for 24 hours, so a
retry within that time is answered with the first result rather than acted on twice.

A contact form takes `5/hour` from one visitor address on each website, on top of
the publishable write limits, and 200 messages a day per website in each mode,
on the website's own clock. Past the day's messages it answers `429` with the code
`daily_limit_reached` until midnight, and those refusals are not counted against the month.

Each website records up to 50,000 AI crawler hits a month and as
many from other crawlers. Past that, crawlers are not recorded until the first of the month.