Лимиты запросов

У каждого API-ключа есть лимит на число запросов в единицу времени. На этой странице — сам лимит, как выглядит ответ при превышении и как снизить число запросов в интеграции.

Сам лимит

Бюджет считается по ключу: у каждого ключа своя независимая квота, даже если несколько ключей принадлежат одной школе или используются с одного IP-адреса. Окно — 60 секунд.

Потолок запросов в минуту зависит от тарифа школы-владельца ключа:

Тариф	Запросов в минуту
Базовый / Эконом	120
Стандарт	120
Расширенный	300
PRO	600

120 — это базовое значение: оно действует на тарифах Базовый и Стандарт, а также как запасное значение, если тариф школы не удалось определить. Явных заголовков с лимитом (X-RateLimit-Limit и подобных) API не отдаёт — свой актуальный лимит смотрите по тарифу школы в таблице выше.

Что приходит при превышении

Ответ — 429 с кодом rate_limit_exceeded и заголовком Retry-After:

curl -i https://platformapi.bigbencrm.ru/api/public/v1/groups \
  -H "Authorization: Bearer bb_a1b2c3d4_M8x1F0qWn9..."

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

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Превышен лимит запросов для этого API-ключа. Повторите запрос позже."
  }
}

Retry-After — целое число секунд до следующей доступной попытки. Других заголовков про лимит (X-RateLimit-Remaining и подобных) API не отдаёт — узнать текущий остаток бюджета до первого 429 нельзя, ориентируйтесь на счётчик запросов на своей стороне.

Практика: ретраи

При 429 подождите ровно Retry-After секунд и повторите запрос — не раньше. Если ошибка повторяется несколько раз подряд (например, несколько интеграций одной школы делят один ключ), увеличивайте паузу сверх Retry-After, чтобы не выстраивать очередь синхронных ретраев:

#!/usr/bin/env bash
url="https://platformapi.bigbencrm.ru/api/public/v1/groups"
key="Authorization: Bearer bb_a1b2c3d4_M8x1F0qWn9..."
headers_file=$(mktemp)

status=$(curl -s -o /dev/null -w '%{http_code}' -D "$headers_file" "$url" -H "$key")

if [ "$status" = "429" ]; then
  retry_after=$(grep -i '^Retry-After:' "$headers_file" | tr -dc '0-9')
  sleep "${retry_after:-5}"
  # повторить запрос
fi

rm -f "$headers_file"

Экспоненциальная пауза

Если 429 повторяется без явной причины (не разовый всплеск), увеличивайте паузу на каждой следующей попытке — например, удваивайте её, начиная от Retry-After, и ограничьте число попыток. Это защищает от ситуации, когда несколько параллельных процессов синхронно бьются в один и тот же лимит.

Как снизить число запросов

• Пагинация. У списковых методов есть page и per_page (максимум 100, по умолчанию 20) — забирайте максимум за один запрос вместо множества мелких.
• Инкрементальная синхронизация. У ресурсов с полем последнего изменения есть параметр updated_since (ISO8601) — запрашивайте только то, что изменилось с прошлой синхронизации, вместо полной выгрузки каждый раз. Первая синхронизация всё равно должна быть полной (без updated_since) — подробности и оговорка про legacy-записи без даты изменения в «Сценариях использования».
• Окно дат для расписания. GET /lessons принимает from/to и не отдаёт больше 92 дней за раз — разбивайте длинные периоды на несколько запросов сразу, это дешевле, чем добирать данные повторами после 429.

Дальше

• Коды ошибок — остальные коды и что с ними делать.
• Справочник API — параметры пагинации и фильтров по каждому эндпоинту.