Rate limits, retries and the one header that makes them safe
A limit is not a punishment. It is the reason a free service can stay free and open to programs at the same time.
What is limited, and by what
Limits are fixed windows counted either per address or per account. A program with no key may create ten pages a day from one address; with a key, ten pages an hour on the account it belongs to. Validation, uploads by URL, imports, claim links and the MCP endpoint each have their own window, all of them generous for real work and tight for a loop.
Addresses are never stored raw: the counter is keyed by a salted hash, the same way visitor statistics are. A limiter row is a write, and the privacy page promises no raw address is ever written — that promise includes this.
- When a window is exhausted the answer is 429 with a code of rate_limited.
- The body carries retryAfter in seconds, and the same value is in the Retry-After header.
- Wait that long. Do not retry immediately, and do not spread the same work across several addresses.
- If you need more than the window allows, that is a conversation, not a workaround.
Why an idempotency key beats a retry loop
- A create that times out may still have succeeded. Retrying blindly produces a second account on a name that is now taken.
- Send an Idempotency-Key header with the create and a repeat returns the first answer instead of making anything.
- The key is scoped to the caller, so two clients cannot read each other’s replies, and it lives for a day.
- Any unique string works: the task id, a hash of the request, the address plus a timestamp.
Limits that are not about speed
Two more ceilings exist for a different reason. A program may create ten pages on one account — a person adding pages by hand has no limit at all, because a person clicking a button is not a loop. And a page holds eighty blocks, which is far more than any page should have and far less than a generator will produce if nothing stops it.
Pages made by a program and never claimed by a person are swept: unpublished after thirty days if nobody has ever visited them, deleted after sixty. One visit, ever, exempts a page for good.