Клиент должен обрабатывать 429 Too Many Requests. Лимиты могут различаться между окружениями и меняться со временем, поэтому не полагайтесь на фиксированное число запросов, если оно не указано в контракте метода.

Рекомендуемое поведение

  1. Распределяйте массовую работу во времени вместо резких всплесков.
  2. Ограничивайте параллелизм каждого воркера и всей организации.
  3. Повторяйте ответы 429 с ограниченной экспоненциальной задержкой и джиттером.
  4. Учитывайте Retry-After, если заголовок присутствует в ответе.
  5. Прекращайте попытки после заданного количества и сообщайте об ошибке.
function retryDelay(attempt: number, retryAfterSeconds?: number) {
  if (retryAfterSeconds !== undefined) return retryAfterSeconds * 1_000;

  const exponential = Math.min(30_000, 500 * 2 ** attempt);
  return exponential + Math.random() * 250;
}

Избегайте синхронных повторов

Джиттер не позволяет множеству воркеров повторять запрос одновременно. Используйте его, даже если все воркеры применяют одинаковую базовую задержку.

Записывайте статус ответа, метод, номер попытки, задержку и x-request-id. Не добавляйте API-ключ или конфиденциальное тело запроса в метрики и журналы.

См. Ошибки и повторные запросы для правил по кодам состояния и идемпотентности.