In this section · 6 articles

API rate limits

How many requests a minute each kind of endpoint accepts, how the limits are counted, the headers that tell you where you stand, and how to handle a 429.

Applies to
Core 12.8 and later
Who can do this
Developer
On this page

Every request to your Laramin's API counts against the general limit. Some endpoints also have a tighter limit of their own. A request that goes over either one is refused with 429 and RATE_LIMITED.

The limits

LimitRequests a minuteApplies to
General60Every request under /api/, on top of any limit below
Sign-in5Mobile sign-in, changing a password from the app, social sign-in from the app, and unlocking a password-protected blog article
Token refresh10Mobile token refresh, counted per person
Two-factor10The two-factor step of a mobile sign-in
Sign-up3Creating an account from the mobile app
Password reset3Asking for a reset code and resetting the password
Sign-up code resend3Resending a sign-up verification email, counted per sign-up
Verification10Entering a sign-up verification code
Public30Public settings, and public endpoints that record something, such as Blog's view and share counters or Property CRM's inquiries
Public read120Public reference data, static fields and options, and most modules' public reads
Mobile120Social Login's mobile endpoints
Help Center30GET /api/v1/help/me

These are the defaults. Whoever runs the server can change them in config/api.php. Modules may add limits of their own, such as Headless CMS's delivery limit: their API reference pages give them.

How requests are counted

  • Each limit is counted per signed-in person, or per IP address when nobody is signed in. These are counted differently:
    • Token refresh is counted per person whose refresh token it is, so phones on one network don't share it.
    • Sign-up code resend is counted per sign-up.
    • The General and Mobile limits count a request made before sign-in per IP address and X-Device-Id together, so each phone has its own count. One IP address may still make at most 600 such requests a minute on the general limit, and 1,200 on the Mobile limit, whatever device ids it sends. Send the same X-Device-Id from each installed app.
  • Each limit has its own count. A burst of sign-ups doesn't use up the sign-in allowance.
  • Counts run over one minute.
  • Each Laramin, and each tenant on a shared installation, counts separately.

Careful: Sign-ins are still counted per IP address, so every phone behind one office network or mobile carrier gateway shares the same 5 sign-ins a minute. If your Laramin sits behind a load balancer, CDN or reverse proxy, whoever runs the server must set TRUSTED_PROXIES to the proxy's addresses. Otherwise every request seems to come from the proxy, and everyone shares each limit that's counted per address.

Headers

HeaderWhenValue
X-RateLimit-LimitEvery answerThe limit for the count being reported. When an endpoint also has a limit of its own, the two headers report whichever count has fewer requests left. For example, public settings report the public limit of 30, and public reference data reports the general limit of 60, because that's tighter than its own 120.
X-RateLimit-RemainingEvery answerRequests left in the current minute.
Retry-AfterOn a 429Seconds until you may try again.
X-RateLimit-ResetOn a 429When the count resets, as Unix time in seconds.

Handle a 429

  1. Stop sending to that endpoint.
  2. Wait the number of seconds in Retry-After.
  3. Try again. If you're refused again, wait longer each time.
JavaScript
async function withRetry(doRequest, attempts = 3) {
  for (let i = 0; i < attempts; i++) {
    const res = await doRequest();
    if (res.status !== 429) return res;
    const wait = Number(res.headers.get('Retry-After') || 2 ** i);
    await new Promise((r) => setTimeout(r, wait * 1000));
  }
  throw new Error('Rate limited: giving up');
}

Stay under the limits

  • Cache answers that rarely change, such as settings and reference data. Public reads send an ETag, so you can ask "has this changed?" cheaply. See Paging, filtering, sorting and caching.
  • Ask for bigger pages, up to the endpoint's maximum, rather than many small ones.
  • Use webhooks to hear about changes instead of polling. See Choose between the API, webhooks and a public API.
  • A website calling public endpoints from visitors' browsers is counted per visitor. Calling them from your web server puts every visitor on one count.