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

У каждого API-ключа есть устойчивый лимит запросов в секунду, производный от вашего тарифа (Free 1 req/s → Max 60 req/s — см. Цены). Лимиты обеспечиваются токен-бакетом: всплески вплоть до вашей минутной ёмкости разрешены, затем запросы сглаживаются до устойчивой ставки.

Когда вы ограничены

{ "error": "rate_limited", "retry_after_ms": 850 }

HTTP 429, error: "rate_limited".
retry_after_ms сообщает минимальное время ожидания перед повтором.
Заголовок x-ratelimit-remaining в каждом ответе сообщает, сколько запросов осталось в эту минуту.

Параллелизм

Помимо ставки в секунду, есть ограничение на запросы в обработке. Если вы выпускаете много запросов сразу, вы можете увидеть:

409 request_in_progress — идентичный идемпотентный запрос уже выполняется.
503 too_many_concurrent_requests — слишком много параллельных запросов в обработке; сделайте задержку и повторите.

Обработка лимитов

Уважайте retry_after_ms; иначе используйте экспоненциальную задержку с джиттером.
Держите на стороне клиента ограничение параллелизма, согласованное со ставкой вашего тарифа.
Официальные SDK автоматически повторяют 429/503.