Skip to Content
Developers

Rate limits

120 requests a minute for each key, the headers that count them and how to back off.

The numbers

WhoLimitOver the limit
Each key120 requests a minute by default429 rate_limited until the minute is over
Each address without a working key60 requests in 10 minutes429 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 countsLimit
Booking requests from one address10 an hour
Bookings for one phone number5 an hour
Bookings for one email3 an hour
Open bookings made from one address4

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:

HeaderMeaning
RateLimit-LimitRequests this key may make in a minute. 120.
RateLimit-RemainingRequests left in this minute.
RateLimit-ResetSeconds until the count starts again.
HTTP/1.1 200 OK
RateLimit-Limit: 120
RateLimit-Remaining: 87
RateLimit-Reset: 41

Over 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_after or paid_after instead of walking a whole list each time. See Pagination.
  • Watch RateLimit-Remaining. When it reaches 0, wait RateLimit-Reset seconds 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.

On this page