Límites

Límite	Valor	Cuando se pasa
Peticiones por llave	60 por minuto	429 throttled con Retry-After
Llaves inválidas por dirección IP	30 por minuto	429 throttled con Retry-After, para toda llamada desde esa dirección
Días de un rango	92 (un trimestre)	400 range_too_long
Empleados por página del Detalle	100 por defecto, hasta 200 con page_size	Un page_size mayor da 200

Un mes de una empresa de 2 000 personas es una llamada al Resumen y 20 al Detalle: cerca de medio segundo cada una, muy dentro de las 60 por minuto.

429: más despacio

Una llamada frenada responde los segundos que hay que esperar dos veces, en la cabecera Retry-After y en el cuerpo:

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

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

Como en todo este API, detail es un mensaje para una persona, en español; su programa lee code. Espere ese tiempo y repita la llamada. Pedir las páginas del Detalle una tras otra, y no todas a la vez, lo mantiene debajo del límite.

La cuenta de llaves inválidas existe para que nadie pueda probar llaves contra Kabal. Se cuenta por dirección, antes de mirar la llave, así que una llave buena mandada desde la misma dirección que una mal configurada también espera: un 401 significa corregir la llave, nunca repetirla.

503: mantenimiento

Mientras Kabal está en mantenimiento, toda llamada responde 503 con el código maintenance y Retry-After: 60. Suele durar minutos. Vuelva a intentar después de ese tiempo; sus números siguen donde estaban.

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

Tamaño y tiempo

Las respuestas son JSON en UTF-8. El Resumen de 2 000 personas pesa unos 1,2 MB; una página de 100 personas del Detalle de un mes, unos 3 MB. Las respuestas pueden llegar comprimidas: mande Accept-Encoding: gzip y deje que su cliente HTTP descomprima, lo que reduce una página del Detalle unas veinte veces cuando ocurre. Cuente igual con el tamaño sin comprimir.

Dé a cada llamada un tiempo de espera de al menos 60 segundos.