Rate limits
Enough for any personal automation, tight enough that a loop gone wrong cannot flood your groups.
The numbers#
| Limit | Sustained | Burst | Applies to |
|---|---|---|---|
| Per key | 2 requests a second | 30 | Every request the key makes, reads and writes alike |
| Per address | 10 requests a second | 20 | Everything from one IP address, keys or not |
Both are token buckets: you can spend the burst at once, and it refills at the sustained rate. A backup that reads 30 pages in a second is fine; one that reads 300 has to pace itself to two a second after the first 30.
GET /v1/developer/key returns the key's own limit as rate_limit (per_second, burst), so a client can read it instead of hard-coding it.
When you hit one#
The answer is 429 with the code rate_limited:
HTTP/1.1 429 Too Many Requests
Retry-After: 2
Content-Type: application/json; charset=utf-8
{"error":{"code":"rate_limited","message":"too many requests for this key; slow down and retry"}}The per-key limit sends Retry-After in seconds. The per-address limit does not; wait about a second before trying again.
Retrying is always safe for reads, and safe for writes as long as you resend the same id: a write that did land replays instead of writing twice (Idempotency).
A backoff to copy#
Retry 429 and 5xx, honour Retry-After, add jitter, and give up after a few tries. Everything else is an answer, not a hiccup.
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
async function withBackoff(url, init = {}, tries = 5) {
for (let attempt = 0; ; attempt++) {
const res = await fetch(url, init);
const retryable = res.status === 429 || res.status >= 500;
if (!retryable || attempt === tries - 1) return res;
const header = Number(res.headers.get("Retry-After"));
const wait = header > 0 ? header * 1000 : Math.min(8000, 500 * 2 ** attempt);
await sleep(wait + Math.random() * 250);
}
}
// The body, and so the id inside it, is built once, outside the retries.
const body = JSON.stringify({ id: uuidv7(), description: "Lunch", amount_minor: 45000 });
const res = await withBackoff(`${API}/v1/groups/${groupId}/expenses`, {
method: "POST",
headers: { ...headers, "Content-Type": "application/json" },
body,
});import random, time
def with_backoff(method: str, url: str, tries: int = 5, **kw):
for attempt in range(tries):
r = session.request(method, url, **kw)
retryable = r.status_code == 429 or r.status_code >= 500
if not retryable or attempt == tries - 1:
return r
header = r.headers.get("Retry-After", "")
wait = float(header) if header.isdigit() else min(8.0, 0.5 * 2 ** attempt)
time.sleep(wait + random.random() * 0.25)
# The body, and so the id inside it, is built once, outside the retries.
bill = {"id": uuid7(), "description": "Lunch", "amount_minor": 45000}
r = with_backoff("POST", f"{API}/v1/groups/{group_id}/expenses", json=bill)For batch jobs, pace yourself instead of waiting for 429s: a 500 ms pause between requests keeps you under the sustained rate indefinitely.
MCP counts too#
A tool call is one request to POST /mcp plus the REST calls the tool makes on your behalf, all against the same key. Most tools make one; add_expense and record_payment make two, because they read the group first to learn its currency and your member id. So one "add a bill" from an assistant spends three requests.
Other limits#
Some limits are about the product rather than the rate:
| Limit | Code when reached |
|---|---|
| 50 members in a group | group_full |
| 30 comments an hour per member, 200 per bill | comment_rate_limited, too_many_comments |
| A page of bills is 1 to 100 (20 by default) | bad_request |
| A capture's text is up to 2,000 characters | invalid_capture |