Rate limits

Each API key has its own limit: 1000 requests per rolling hour unless the key was created with another number. The limit belongs to the key, not to the campground or to your server’s address, so the key Camping Beispielsee gave you and the key of the next campground each have their own 1000.

How it counts

• Rolling hour. Grondia remembers the time of each request your key made in the last 3600 seconds. When 1000 of them fall into that window, the next request is refused until the oldest one is more than an hour old.
• What counts: every request that got past the key and scope checks, whatever its answer, 400, 404 and 409 included. A repeat that an Idempotency-Key answers from storage counts too.
• What does not count: a request refused with 401 or 403, and a request refused with 429. Retrying while you are over the limit does not push the end of the wait further out.

When the limit is reached

The API answers 429 Too Many Requests with a Retry-After header, the number of seconds until the oldest request in your window drops out and one request is free again:

HTTP/1.1 429 Too Many Requests
Retry-After: 37
Content-Type: application/json

{"detail": "Request was throttled. Expected available in 37 seconds."}

Wait that long, then go on. One request is free after the wait, not a full hour’s worth: if you were sending fast, the next ones may be refused as well, each with its own Retry-After.

Successful answers carry no headers about the limit, so the API does not tell you how much is left. Count your own requests per key if you need to know.

Staying under it

1000 an hour is one request every 3.6 seconds on average. Bursts are fine as long as the hour stays under 1000.

• Use webhooks instead of polling. A webhook costs you nothing until something happens, and then one request to fetch the booking.
• Ask for full pages. page_size=200 reads a list in a quarter of the requests the default 50 takes.
• Ask only for what changed. A sweep with updated_since reads the bookings that changed, not all of them.
• Keep what rarely changes. The list of sites changes seldom; read it once a day, not before every booking.

Channel managers turns this into a request budget for a whole campground. The admin screen creates every key with the default limit. If your product needs more for a campground, ask Felix, felix@grondia.com, or Siro, siro@grondia.com, and say how many requests an hour and why.

In the sandbox

The sandbox key has the same limit, 1000 requests per rolling hour, so you can watch a 429 and its Retry-After there. Other developers may be using the sandbox at the same time, possibly with the same key, so its hour can run out sooner than your own requests explain.