Rate limits, and what happens when you cross one

Shape: How it actually works
Plates: lede · table · dial · note
Why: Documentation is read by somebody already in trouble, so lead with behaviour and not policy. `table` for the limits, because these are values to be read off the page and that is exactly what `table` is for. Then `dial` — a developer who drags the rate and watches the response change understands the burst allowance in four seconds, and no paragraph achieves that.

There are two limits and they behave differently. Nearly every support ticket about rate limiting is somebody hitting the second one while watching the first.

The limits

Plan	Sustained	Burst	Window
Free	1/s	10	60s
Team	20/s	200	60s
Enterprise	Negotiated	Negotiated	60s

Burst is a bucket, not a second limit. It refills at the sustained rate.

Drag the request rate

Bucket	Response	Retry-After
Steady	200	—

Exactly at the sustained rate. Sustainable forever, with no headroom.

Requests per second20req/s

underover

The bucket drains faster than it fills above the sustained rate. That is the whole mechanism.

This is a sample. To author the same thing about your own subject, just name it. Your assistant can read this template, and will write you the same document about what you know.

Using the Ario tools, make me the "Product guide"
template for our webhooks.
Show me the shape before you build anything.

New here? How to connect one.

Other samples