Rate limits

The headers on every answer

Bookatu sends the fields of the IETF RateLimit header draft (draft-ietf-httpapi-ratelimit-headers), one set on every answer:

A browser may read all of them: they are listed in Access-Control-Expose-Headers.

HTTP/1.1 200 OK
RateLimit-Limit: 30
RateLimit-Remaining: 29
RateLimit-Reset: 60
RateLimit-Policy: 30;w=60, 2000;w=86400
Bookatu-Version: 2026-10-30
Bookatu-Livemode: true

The limits

A key is held to the plan of the business it belongs to. Keyless calls are counted per address at each business, so one busy client never uses up another's budget, and a key sent to a keyless endpoint is not counted on the key. A call refused before the endpoint counts it (a key without the endpoint's scope, another business's key, a business that is not found) is not counted on the key either. An answer the MCP server sends before it counts the call (the notifications/initialized 202, a parse error) says your key's windows as they stand.

Standard and raised

Every key is on the standard tier: its plan's numbers above. A Bookatu platform admin can put a live key on the raised tier, which gives that key, and its business's keys together while it calls, 4 times the plan's numbers: 120 a minute instead of 30 on Solo. Ask Bookatu support when your integration needs it, naming the key's prefix and the business. Only a platform admin can change a tier, and every change is in the business's audit log.

Test keys are always held to the sandbox's limits, whatever their tier: raised never raises a test key.

When you get a 429

The answer is a 429 with Retry-After, the headers above, and a body saying when to retry. Its words differ by endpoint; the status and Retry-After never do. Over MCP it is a JSON-RPC error -32000, Rate limit exceeded, with error.data.retryAfterSec.

HTTP/1.1 429 Too Many Requests
Retry-After: 17
RateLimit-Limit: 30
RateLimit-Remaining: 0
RateLimit-Reset: 17
RateLimit-Policy: 30;w=60, 2000;w=86400

{ "error": "Rate limit exceeded", "retryAfterSec": 17, "livemode": true }

• Wait at least Retry-After seconds before calling again.
• Back off exponentially on repeated 429 and 5xx answers, with jitter (a random part in each wait), so many clients do not retry in step.
• Watch RateLimit-Remaining and slow down before it reaches 0.
• Cache what rarely changes: GET /business, /services and /staff.
• Use webhooks to learn about changes instead of polling for them.

async function call(url, init, attempt = 0) {
  const res = await fetch(url, init);
  if ((res.status === 429 || res.status >= 500) && attempt < 5) {
    const retryAfter = Number(res.headers.get("Retry-After")) || 2 ** attempt;
    const jitter = Math.random() * 1000;
    await new Promise((r) => setTimeout(r, retryAfter * 1000 + jitter));
    return call(url, init, attempt + 1);
  }
  return res;
}