Limits

Every limit in one place. The first part applies to every request you make. Rate Capture's own limits, such as how many properties a run can hold, are at the end.

In short

Limits keep the API fast for everyone. By default each key can make 600 reads and 60 writes a minute, a company can have 5 runs going at once, and a call over a limit gets a 429 with the number of seconds to wait. Beacon can raise any limit: email support.

Request limits

Limit Default Over it
Read requests per key: every GET, and every call to the Lighthouse-compatible API 600 a minute 429 rate_limited, Retry-After: 60
Write requests per key: every POST and DELETE 60 a minute 429 rate_limited, Retry-After: 60
Unrecognised keys from one IP address 20 an hour 429 rate_limited, Retry-After: 3600

Reads and writes are counted separately. Each key has its own count for each calendar minute, so a burst of polling never uses up your writes.

The figures in these tables are the defaults. Beacon can set different limits for your company. Your company's own figures are in the web app, under Company > API, in Your limits.

Company limits

Limit Default Over it
Live keys. Revoked and expired keys don't count. 50 per company The app won't create another key until you revoke one.
Rate Capture runs queued or running at once 5 per company 429 too_many_active_runs, with no Retry-After

What a 429 looks like

Over a request limit, the answer is 429 rate_limited with a Retry-After header. It gives the number of seconds to wait before trying again: wait at least that long. The Rate Capture API has no headers counting how many requests you have left. The Lighthouse-compatible API does, see below. 

HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json; charset=utf-8

{"error":{"code":"rate_limited","message":"Too many requests for this API key. Wait a minute and try again."}}

A 429 rate_limited from the Lighthouse-compatible API has the same status, in Lighthouse's shape: message and an errors list.

Too many runs at once is different. The answer is 429 too_many_active_runs, with no Retry-After. details says how many runs are going and what your limit is. Nothing was charged. Start the run again when one of yours has finished. 

{
  "error": {
    "code": "too_many_active_runs",
    "message": "The company already has as many queued or running runs as it may; start this one when one has finished.",
    "details": {"active": 5, "limit": 5}
  }
}

Neither kind of 429 is kept against an Idempotency-Key, so you can send the same key again. See sending a write again.

Rate-limit headers in the Lighthouse-compatible API

Like Lighthouse, every answer from the Lighthouse-compatible API to a request with a recognised key says where the key stands for the current minute.

Header Value
X-RateLimit-Limit The key's reads a minute, 600 unless Beacon has raised it.
X-RateLimit-Remaining Reads left in the current minute, and 0 on a 429.
X-RateLimit-Reset Seconds until the current minute ends and the count starts again.

An answer to a request with no key, or an unrecognised one, has no count to give, so it has none of these headers.

Raising a limit

Beacon can raise your company's limits on request: reads and writes a minute per key, runs at once, live keys, and properties in a report. Email support@getbeacon.cloud to ask.

Rate Capture limits

Limits on what you send to the Rate Capture API, and on pages of results.

Limit Value Over it
Properties in a report or run created through the API Up to your company's limit, 50 by default; your company's figure is under Company > API. A repeated URL is kept once. 422 validation_failed
Stay length, nights 1 to 7 nights, one per report 422 validation_failed
Currencies the API accepts 30: AED, AUD, BGN, BRL, CAD, CHF, CNY, CZK, DKK, EUR, GBP, HKD, HUF, IDR, ILS, INR, JPY, KRW, MXN, MYR, NOK, NZD, PLN, RON, SEK, SGD, THB, TRY, USD, ZAR 422 validation_failed
Report name 1 to 100 characters 422 validation_failed
Run reference 1 to 128 characters, with no comma 422 validation_failed
Check-in dates in one run 365, starting on today's date in the run's time zone (timeZone)
Retrying a run's failed checks Once every 10 minutes for each run, counting the retries you start with the API or in the app. A retry when nothing has failed doesn't start the wait. 409 retry_cooldown
References in one reference filter on GET /v1/runs Up to 100, separated by commas 422 invalid_reference
Page size, limit 1 to 200 for reports and runs, 1 to 2000 for rows. See lists and pages. 422 invalid_limit
Page size on /lighthouse/v3/hotels, per_page 1 to 100 400
Idempotency-Key Up to 200 characters, remembered for 24 hours 422 invalid_idempotency_key

The rates filters, such as los and persons, have their own ranges, listed in the reference. A value out of range answers 400 invalid_filter.