AthausDocs

REST API: limits and throttling

How many calls /v1 accepts per key and per office, which headers show the state and what to do on a 429.

Last updated:

/v1 throttles with a bucket: a stock of calls at once that refills at a fixed rate. It counts per key, and a cap for the whole office applies on top.

BucketRateAt once
Read, per key10 per second100
Read, per office, across all keys40 per second400
Write, per key2 per second60
Write, per office, across all keys8 per second240

The cap of the office is four times that of a key. Several keys of one office do not share one limit, but they do not run without an upper bound either.

The headers

Every response shows the state of the bucket that applies:

RateLimit-Policy: "read";q=100;w=10
RateLimit: "read";r=57;t=5
PartMeaning
"read"the name of the bucket. There are read and read-office
qthe stock at once
wseconds until an empty bucket is full again
rthis many calls are still free
tseconds until the bucket is full again

The syntax follows the draft draft-ietf-httpapi-ratelimit-headers. It is still a draft and may change.

When it gets too many

The answer is 429 with rate_limited and the header Retry-After in seconds. The member detail names the cause: the key, the office or too many failed attempts from one address.

HTTP/1.1 429 Too Many Requests
Retry-After: 3

Wait that long and send the same request again. A throttled request is never executed, so repeating it is safe.

For lists, limit=100 saves calls compared with many small pages (Pagination).

Keep reading

On this page