Справочник
Ограничения частоты
Ограничения защищают API от наплыва запросов, а не от обычных реселлеров. У каждого аккаунта есть одно ограничение в минуту, растущее вместе с расходами, а для тяжёлых действий действует несколько узких ограничений. Правила, относящиеся к одному заказу, например ожидание восполнения, возвращают собственный код ошибки вместо 429.
Уровни ограничения
На IP
20 000 запросов / минуту / IP-адрес
Применяется до проверки ключа, чтобы ограничить перебор ключей грубой силой. Общий для всех ключей за одним IP. Значение по умолчанию задаётся глобально и не настраивается пользователем.
Общее окно аккаунта
120–2 400 запросов / скользящие 60 секунд
Все активные API-ключи аккаунта используют один счётчик. Лимит задаёт фиксированная шкала успешных расходов за всё время, если администратор не установил индивидуальный RPM.
По действию
Зависит от действия
У services, catalog, cancel, refill и действий с вебхуками есть собственные узкие ограничения, показанные ниже. Они добавляются к ограничению аккаунта, а не заменяют его.
Ограничения по действиям
Эти ограничения считаются на аккаунт в минуту. Ответ 429 от одного из них указывает action в X-RateLimit-DeniedBy. Cancel и refill считают идентификаторы заказов, а не запросы, поэтому один вызов для 10 заказов расходует 10 из доступных вам в минуту идентификаторов. Cancel или refill с большим числом идентификаторов, до 100, проходит, если это ваш первый вызов в минуте, и расходует всю минуту.
| Действие | В минуту | Что считается |
|---|---|---|
| services | 10 | Запросы |
| catalog | 30 | Запросы |
| cancel | 30 | Идентификаторы заказов |
| refill | 30 | Идентификаторы заказов |
| webhook.* | 10 | Запросы |
Шкала успешных расходов за всё время
Ограничение вашего аккаунта зависит от накопленных за всё время успешных расходов; более высокий уровень сразу открывает более высокое ограничение. Потолок по IP в 20 000 запросов в минуту действует до проверки ключа. Администратор может задать для аккаунта прямое ограничение, до 10 000. Уровень вашего аккаунта указан в заголовке X-RateLimit-Tier и на вашей странице API.
| Уровень | Минимальные расходы за всё время | Запросов / минуту |
|---|---|---|
| 0 | 0 $ | 120 |
| 1 | 10 $ | 300 |
| 2 | 50 $ | 600 |
| 3 | 100 $ | 900 |
| 4 | 500 $ | 1 200 |
| 5 | 1 000 $ | 1 800 |
| 6 | 2 500 $ | 2 400 |
Заголовки ответа
Заголовки ответа
X-RateLimit-Limit- В обычном ответе — действующий общий лимит запросов аккаунта в минуту. В ответе 429 — лимит отклонившего слоя.
X-RateLimit-Remaining- В обычном ответе — число запросов, оставшихся в общем окне аккаунта. В ответе 429 — остаток отклонившего слоя.
X-RateLimit-Reset- Относительное число секунд до сброса указанного окна; это не Unix timestamp.
X-RateLimit-Tier- Уровень, полученный за успешные расходы за всё время (0–6). Индивидуальный лимит RPM не меняет это значение.
X-RateLimit-DeniedBy- Передаётся в ответе 429, когда запрос отклоняет именованный ограничитель: "ip", "api_requests_per_minute" или "action".
Retry-After- При повторяемом ответе 429 или 503 подождите перед повтором не меньше числа секунд из Retry-After. Для action=add после ожидания используйте тот же ключ идемпотентности.
Обработка ответов 429
Ждите по Retry-After, если он есть.
Иначе ждите число секунд из X-RateLimit-Reset. Оба значения — относительные задержки, а не время по часам; перед повтором добавьте случайный разброс.Читайте X-RateLimit-DeniedBy.
Он называет ограничение, отклонившее вызов. Смена ключа не поможет, потому что ограничения аккаунта, IP и действия общие.Используйте вебхуки вместо опроса.
Вебхуки приходят как минимум один раз, поэтому делайте обработчик идемпотентным и проверяйте важное черезaction=status.Объединяйте, где можете.
Status, cancel и refill принимают до 100 идентификаторов в одном запросе; подсчёт идентификаторов заказов для cancel и refill сохраняется.