Limits

Limit	Value	When it is passed
Requests per key	60 per minute	429 throttled with Retry-After
Invalid keys per IP address	30 per minute	429 throttled with Retry-After, for every call from that address
Days in a range	92 (a quarter)	400 range_too_long
Employees per page of the detail	100 by default, up to 200 with page_size	A larger page_size gives 200

A month for a company of 2 000 people is one call to the summary and 20 to the detail: about half a second each, far inside 60 per minute.

429: slow down

A throttled call answers with the seconds to wait twice, in the Retry-After header and in the body:

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

{ "detail": "…", "code": "throttled", "retry_after": 23 }

As everywhere in this API, detail is a message for a person, in Spanish; your program reads code. Wait that long and repeat the call. Running the pages of the detail one after the other, not all at once, keeps you under the limit.

The count of invalid keys exists so that nobody can try keys against Kabal. It is counted per address, before the key is looked at, so a good key sent from the same address as a misconfigured one waits too: a 401 means fix the key, never retry it.

503: maintenance

While Kabal is in maintenance, every call answers 503 with the code maintenance and Retry-After: 60. It usually lasts minutes. Retry after that time; your numbers are waiting where they were.

{
  "detail": "Kabal está en mantenimiento. Intenta de nuevo en unos minutos.",
  "code": "maintenance"
}

Size and time

Answers are JSON in UTF-8. The summary of 2 000 people weighs about 1.2 MB; a page of 100 people of the detail over a month, about 3 MB. Answers may come compressed: send Accept-Encoding: gzip and let your HTTP client decompress, which shrinks a page of the detail about twentyfold when it does. Plan for the uncompressed size anyway.

Give each call a timeout of at least 60 seconds.