Rate limits
120 requests a minute for each key, the headers that count them and how to back off.
The numbers
| Who | Limit | Over the limit |
|---|---|---|
| Each key | 120 requests a minute by default | 429 rate_limited until the minute is over |
| Each address without a working key | 60 requests in 10 minutes | 429 rate_limited before WeerOm looks at the key |
The count is per key, not per shop. Two tools with their own keys each get 120 requests a minute. Reads and writes count the same.
A page holds up to 100 objects, so one key reads up to 12,000 objects a minute.
Bookings with a public key
A booking made with a public key is a visitor's booking, and it runs under the same limits as the shop's own booking form. Today they are:
| What counts | Limit |
|---|---|
| Booking requests from one address | 10 an hour |
| Bookings for one phone number | 5 an hour |
| Bookings for one email | 3 an hour |
| Open bookings made from one address | 4 |
Over one of them, POST /bookings answers 429 limit_reached with a Retry-After header. Every booking made as a customer, whatever the key, also counts against the shop's own cap on open bookings for one customer, when the shop set one. That answer is 429 limit_reached without Retry-After.
A write key books from a server, where every request comes from one address. It runs under its 120 requests a minute and not under these limits.
The headers
Every answer that passed the key check carries three headers:
| Header | Meaning |
|---|---|
RateLimit-Limit | Requests this key may make in a minute. 120. |
RateLimit-Remaining | Requests left in this minute. |
RateLimit-Reset | Seconds until the count starts again. |
HTTP/1.1 200 OK
RateLimit-Limit: 120
RateLimit-Remaining: 87
RateLimit-Reset: 41Over the limit, the answer is 429 with a Retry-After header in seconds:
HTTP/1.1 429 Too Many Requests
Retry-After: 23{
"error": {
"code": "rate_limited",
"message": "This key may make 120 requests a minute. Try again in 23 seconds.",
"request_id": "req_9c0d1e2f3a4b5c6d"
}
}Back off
On a 429, wait the seconds in Retry-After and send the same request again. Requests sent in the meantime answer 429 as well.
async function weerom(path) {
for (let attempt = 0; attempt < 5; attempt++) {
const response = await fetch(`https://api.weerom.com/v1${path}`, {
headers: { Authorization: `Bearer ${process.env.WEEROM_KEY}` },
});
if (response.status !== 429) return response;
const seconds = Number(response.headers.get("Retry-After") ?? "60");
await new Promise((done) => setTimeout(done, seconds * 1000));
}
throw new Error("Still rate limited after 5 tries");
}Stay under the limit
- Ask for
limit=100. One request for 100 objects costs the same as one for 25. - Sync with
updated_afterorpaid_afterinstead of walking a whole list each time. See Pagination. - Watch
RateLimit-Remaining. When it reaches 0, waitRateLimit-Resetseconds before the next request. - Run one sync at a time for each key.
- Let webhooks tell you about bookings and payments instead of asking every minute. A message from WeerOm costs no request.
- Poll on a schedule that fits. A job that asks every 5 minutes for what changed costs a few requests each time, far under 120 a minute.