Лимиты частоты

Ограничения на количество запросов для токена, значение по умолчанию и максимум, и что делать при 429.

Лимиты частоты действуют на токен, а не на команду, пользователя или IP. Два токена одной команды имеют независимые бюджеты — именно поэтому каждой интеграции стоит выдавать собственный токен, а не делить один на всех.

Лимит выбирается при создании токена и меняется его редактированием. Значение вне диапазона 1..600 отклоняется при создании ошибкой VALIDATION_ERROR, а не молча обрезается: лимит, который вы не получили, заслуживает ошибки, а не сюрприза.

Окно — скользящие 60 секунд, проверка выполняется на API-шлюзе до того, как запрос дойдёт до сервиса. Отклонённый запрос не выполняется, поэтому не стоит вам ничего, кроме самого round-trip.

Как выглядит 429

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

{
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "API token rate limit exceeded"
}

Retry-After содержит целое число секунд до освобождения бюджета. Заголовок присутствует всегда, когда ограничитель может его вычислить, и может отсутствовать — отсутствие не является разрешением повторить немедленно. Отступайте в любом случае.

Что с этим делать

429 — временная ошибка. Её нужно повторять. Этим она отличается от всех 4xx выше: 400 или 403 будут падать одинаково всегда, а 429 пройдёт, как только окно сдвинется.

• Соблюдайте Retry-After, когда он есть; при его отсутствии используйте экспоненциальный отступ со случайным разбросом. Равномерные повторы от многих воркеров снова синхронизируются в тот же всплеск, который и вызвал 429.
• Ограничьте число повторов сверху и сообщайте об ошибке, а не зацикливайтесь.
• Обходя коллекцию, берите меньше страниц, но крупнее: limit=100 стоит одного запроса там, где limit=10 стоит десяти. См. Постраничная выдача.
• Предпочитайте вебхуки опросу. Цикл опроса тратит бюджет на вопрос «случилось ли что-нибудь»; вебхук не тратит ничего и сам сообщает, когда случилось.

Два отказа, которые не являются лимитом частоты

Оба — 4xx, и ни один не проходит сам собой:

• 403 IP_NOT_ALLOWED — у токена задан белый список IP, а запрос пришёл не с перечисленного адреса. Добавьте адрес или выпустите токен без белого списка.
• 403 INSUFFICIENT_SCOPE — у токена нет области доступа под то, что он запросил. Повторы только тратят бюджет лимита частоты; токен нужно перевыпустить. См. Аутентификация.

← Вся документация