# Rate limits

Source: https://developers.weerom.com/docs/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
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
HTTP/1.1 429 Too Many Requests
Retry-After: 23
```

```json
{
  "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.

```js tab="JavaScript"
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");
}
```

```php tab="PHP"
<?php
function weerom(string $path): array {
  for ($attempt = 0; $attempt < 5; $attempt++) {
    $wait = 60;
    $curl = curl_init('https://api.weerom.com/v1' . $path);
    curl_setopt_array($curl, [
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('WEEROM_KEY')],
      CURLOPT_HEADERFUNCTION => function ($curl, $line) use (&$wait) {
        if (stripos($line, 'Retry-After:') === 0) {
          $wait = (int) trim(substr($line, 12));
        }
        return strlen($line);
      },
    ]);
    $body = curl_exec($curl);
    if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) !== 429) {
      return json_decode($body, true);
    }
    sleep($wait);
  }
  throw new RuntimeException('Still rate limited after 5 tries');
}
```

```python tab="Python"
import os
import time
import requests

def weerom(path):
    for attempt in range(5):
        response = requests.get(
            f"https://api.weerom.com/v1{path}",
            headers={"Authorization": f"Bearer {os.environ['WEEROM_KEY']}"},
        )
        if response.status_code != 429:
            return response
        time.sleep(int(response.headers.get("Retry-After", "60")))
    raise RuntimeError("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](https://developers.weerom.com/docs/pagination#sync-only-what-changed).
- 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](https://developers.weerom.com/docs/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.
