# Rate limits

URL: /code/platform/rate-limits · Id: `capability:rate-limits`

> Rate limits check each call against its Limits before it runs and count its usage into Meters after, exactly once.

Rate limits check every call against its [Limits](/business/nouns/limit) before it runs and count its usage into [Meters](/business/nouns/meter) after, exactly once. One mechanism bounds request rates, spend and send volume.

## Contract
- A Limit bounds an amount, a count or a rate per period. It sits on a [Permission](/business/nouns/permission), an [Entitlement](/business/nouns/entitlement) or a [Mandate](/business/nouns/mandate), per [Startup](/business/nouns/startup), [Worker](/business/nouns/worker) and [Customer](/business/nouns/customer).
- The check runs before every call and costs one database read.
- A rate over its Limit returns `429` [rate-limited](/code/api/errors/rate-limited) with `Retry-After`. No [Action](/business/nouns/action) is created.
- An amount or count over its Limit holds the Action as `pending` and opens an [Approval](/business/nouns/approval) to raise it. A Worker other than the one stopped answers it.
- Every response carries `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` headers.
- A Meter turns usage [Events](/business/nouns/event) into ledger [Entries](/business/nouns/entry) exactly once. [Invoices](/business/nouns/invoice) read the Meter, so usage and billing never disagree.
- An [Agent](/business/nouns/agent) plans within its Limits. An over-Limit need becomes an Approval, never a retry loop.

## Verbs
| Verb | Object | Event |
| --- | --- | --- |
| [Limit.raise](/business/nouns/limit/raise) | [Limit](/business/nouns/limit) | [`Limit.raised`](/business/events/Limit.raised) |

## Interfaces
- [API](/code/api/reference)
- [SDK](/code/sdk/reference)
- [CLI](/code/cli/reference)
- [MCP](/code/mcp/reference)

## Example
```ts
// tidewise.dev sells tide predictions by API. Every plan allows 100 calls a minute,
// and each call is metered into the Customer's monthly invoice.
import { $ } from 'startup-builder'

await $.Limit.create({ count: 100, period: 'minute' })

// Counts each Prediction.read call into the month.
await $.Meter.create({ unit: 'calls', of: 'Prediction.read', aggregation: 'count', window: 'month' })
```