Основы

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

Число запросов в минуту ограничено. Лимит считается для каждого ключа API отдельно, и для каждой группы ресурсов - свой. Текущее значение приходит в заголовке RateLimit-Limit.

Заголовки

В ответах на запросы с рабочим ключом есть три заголовка:

Заголовок	Что в нём
`RateLimit-Limit`	Сколько запросов разрешено за минуту
`RateLimit-Remaining`	Сколько запросов осталось в текущей минуте
`RateLimit-Reset`	Через сколько секунд счётчик обнулится

Минута отсчитывается от первого запроса после обнуления счётчика.

Если лимит превышен

API отвечает 429 rate-limited и в заголовке Retry-After пишет, через сколько секунд можно повторить:

HTTP/1.1 429 Too Many Requests
Retry-After: 17
RateLimit-Remaining: 0
RateLimit-Reset: 17

У некоторых операций есть своё ограничение поверх общего лимита. Оно тоже отвечает 429 с Retry-After, даже если RateLimit-Remaining больше нуля. Поэтому после 429 ориентируйтесь на Retry-After.

Как повторять запросы

После 429 подождите столько секунд, сколько указано в Retry-After, и повторите запрос.
После 503 и обрыва связи повторяйте с нарастающей паузой: 1 секунда, 2, 4, 8 и так далее. Добавляйте к паузе немного случайного времени, чтобы повторы с нескольких ваших серверов не приходили одновременно.
Ограничьте число повторов и записывайте в лог Request-Id последнего ответа.
Запрос на создание повторяйте с тем же Idempotency-Key - тогда повтор не создаст дубль. См. Идемпотентность.
При массовой загрузке следите за RateLimit-Remaining. Когда он дошёл до нуля, сделайте паузу на RateLimit-Reset секунд.