Reference

Rate limits

Per-endpoint request limits for the Macaaw Public API and how to handle 429 responses.

Limits are counted per user over a 60-second sliding window, separately for each group of endpoints. Sandbox keys share one small limit for everything.

Limits per endpoint group#

Every endpoint#

Headers#

{
  "type": "rate_limit",
  "code": "RATE_LIMITED",
  "detail": "Too many requests. Please wait a moment."
}

Handling 429#

Wait for Retry-After seconds, then retry. Spread bulk work out instead of sending it in bursts, and prefer webhooks to polling.

async function call(url, init, tries = 5) {
  const res = await fetch(url, init);
  if (res.status !== 429 || tries === 0) return res;
  const wait = Number(res.headers.get('Retry-After') ?? 1);
  await new Promise((r) => setTimeout(r, wait * 1000));
  return call(url, init, tries - 1);
}