Rate limits

Rate limits check every call against its Limits before it runs and count its usage into Meters after, exactly once. One mechanism bounds request rates, spend and send volume.

ContractCopy Anchor Link

• A Limit bounds an amount, a count or a rate per period. It sits on a Permission, an Entitlement or a Mandate, per Startup, Worker and Customer.
• The check runs before every call and costs one database read.
• A rate over its Limit returns 429 rate-limited with Retry-After. No Action is created.
• An amount or count over its Limit holds the Action as pending and opens an 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 into ledger Entries exactly once. Invoices read the Meter, so usage and billing never disagree.
• An Agent plans within its Limits. An over-Limit need becomes an Approval, never a retry loop.

VerbsCopy Anchor Link

InterfacesCopy Anchor Link

• API
• SDK
• CLI
• MCP

ExampleCopy Anchor Link

// 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' })