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
| Limit | Requests a minute | Applies to |
|---|---|---|
| General | 60 | Every request under /api/, on top of any limit below |
| Sign-in | 5 | Mobile sign-in, changing a password from the app, social sign-in from the app, and unlocking a password-protected blog article |
| Token refresh | 10 | Mobile token refresh, counted per person |
| Two-factor | 10 | The two-factor step of a mobile sign-in |
| Sign-up | 3 | Creating an account from the mobile app |
| Password reset | 3 | Asking for a reset code and resetting the password |
| Sign-up code resend | 3 | Resending a sign-up verification email, counted per sign-up |
| Verification | 10 | Entering a sign-up verification code |
| Public | 30 | Public settings, and public endpoints that record something, such as Blog's view and share counters or Property CRM's inquiries |
| Public read | 120 | Public reference data, static fields and options, and most modules' public reads |
| Mobile | 120 | Social Login's mobile endpoints |
| Help Center | 30 | GET /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-Idtogether, 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 sameX-Device-Idfrom 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
| Header | When | Value |
|---|---|---|
X- | Every answer | The 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- | Every answer | Requests left in the current minute. |
Retry-After | On a 429 | Seconds until you may try again. |
X- | On a 429 | When the count resets, as Unix time in seconds. |
Handle a 429
- Stop sending to that endpoint.
- Wait the number of seconds in
Retry-After. - Try again. If you're refused again, wait longer each time.
Couldn't copy. Select the code and press Ctrl+C (⌘+C on a Mac).
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.
Thanks. That helps us decide what to write next.
Thanks for telling us what was missing.
You already answered for this article today. Thanks.
We got a lot of answers from your network just now. Try again in a few minutes.
We couldn't send that. Check your connection and try again.
Links in this article
Printed from help.laramin.in. The online article may have changed since.