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

Лимиты по умолчанию

KONERGY ограничивает частоту запросов для защиты сервиса. Ограничения зависят от маршрута; часть из них применяется к IP-адресу. Несколько интеграций за одним IP могут разделять такой лимит.

Индивидуальный параметр rateLimitRpm пока не применяется к трафику. Сохранённое значение не ограничивает расходы и не заменяет общий лимит сервиса. При превышении действующего ограничения сервер возвращает 429 RATE_LIMITED.

Заголовки rate limit

Заголовки X-Quota-*, когда они присутствуют, описывают квоты обработки, а не частоту запросов. Они не гарантируются на каждом маршруте и отсутствуют у бесплатной проверки ключа. При 429 учитывайте Retry-After, если он есть; иначе используйте увеличивающуюся задержку.

Пример ответа 429

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

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Please retry after 12 seconds.",
    "details": {
      "retry_after_seconds": 12
    }
  }
}

Best practices

• Разделяйте квоты и частоту — X-Quota-Global-Remaining относится к квоте обработки. Пауза между запросами сама по себе эту квоту не восстанавливает.
• Учитывайте Retry-After — при получении 429 ждите указанное время, если сервер его передал.
• Exponential backoff — если после ожидания Retry-After запрос снова возвращает 429, увеличивайте задержку экспоненциально
• Пакетная обработка — по возможности группируйте операции, чтобы снизить общее количество запросов
• Кеширование — кешируйте результаты для идентичных запросов на стороне клиента
• Ограничивайте параллелизм — используйте очередь на своей стороне. Создание дополнительных ключей не увеличивает общий лимит сервиса.

Пример обработки rate limit

async function requestWithRetry(url: string, options: RequestInit, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.status !== 429) {
      return response;
    }

    const retryAfter = response.headers.get('Retry-After');
    const waitSeconds = retryAfter ? parseInt(retryAfter, 10) : Math.pow(2, attempt);

    await new Promise((resolve) => setTimeout(resolve, waitSeconds * 1000));
  }

  throw new Error('Rate limit exceeded after max retries');
}

Подробнее об ошибке 429 RATE_LIMITED и других кодах ошибок читайте в разделе Обработка ошибок.