dimesumdevelopers API reference Console Open the app

Rate limits

Enough for any personal automation, tight enough that a loop gone wrong cannot flood your groups.

The numbers#

LimitSustainedBurstApplies to
Per key2 requests a second30Every request the key makes, reads and writes alike
Per address10 requests a second20Everything 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
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.

JavaScript
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,
});

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:

LimitCode when reached
50 members in a groupgroup_full
30 comments an hour per member, 200 per billcomment_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 charactersinvalid_capture