BigBen CRM API

Русский

English

Русский

English

Тема

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

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

Сам лимит ​

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

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

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

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

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

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

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

bash
#!/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) — запрашивайте только то, что изменилось с прошлой синхронизации, вместо полной выгрузки каждый раз.
  • Окно дат для расписания. GET /lessons принимает from/to и не отдаёт больше 92 дней за раз — разбивайте длинные периоды на несколько запросов сразу, это дешевле, чем добирать данные повторами после 429.

Дальше ​