Обмеження запитів

API Qamera AI застосовує обмеження запитів для забезпечення справедливого використання та стабільності платформи. Ліміти застосовуються для кожного API key окремо.

Стандартні ліміти

Кожен API key має ліміт до 60 запитів на хвилину. Цей ліміт поширюється на всі ендпоінти — як GET, так і POST запити враховуються в одній квоті.

Реалізація

Rate limiting використовує лічильник ковзного вікна в пам'яті. Вікно відстежує запити за останній 60-секундний період і відхиляє нові запити після досягнення ліміту.

Оскільки лічильник знаходиться в пам'яті, він скидається при перезапуску API-сервера. Не покладайтесь на цю поведінку — у майбутніх релізах буде використано персистентний rate limiting на базі Redis.

Відповідь 429

Коли ви перевищуєте ліміт запитів, API повертає відповідь 429 Too Many Requests:

{
  "error": "Too many requests. Please retry after a short delay."
}

Стратегії повторних спроб

Експоненціальне відступання (рекомендовано)

Коли ви отримуєте відповідь 429, зачекайте перед повторною спробою. Збільшуйте затримку з кожною послідовною невдачею:

Спроба 1: зачекайте 1 секунду
Спроба 2: зачекайте 2 секунди
Спроба 3: зачекайте 4 секунди
Спроба 4: зачекайте 8 секунд

Додайте невеликий випадковий jitter (0–500 мс) до кожної затримки, щоб уникнути синхронізованих повторних спроб від кількох клієнтів.

Проста затримка

Для простіших реалізацій зачекайте фіксовані 2 секунди після будь-якої відповіді 429 перед повторною спробою.

Розподіл запитів

Якщо ваше навантаження включає пакетні запити, розподіліть їх рівномірно протягом хвилинного вікна. Для 60 запитів на хвилину намагайтесь робити приблизно один запит на секунду.

Приклад: повторна спроба з відступанням

#!/bin/bash
MAX_RETRIES=4
DELAY=1

for i in $(seq 1 $MAX_RETRIES); do
  RESPONSE=$(curl -s -o /dev/null -w "%{http_code}" \
    -H "X-Api-Key: mk_live_abc123.secretvalue" \
    https://qamera.ai/api/external/products)

  if [ "$RESPONSE" -ne 429 ]; then
    echo "Request succeeded with status $RESPONSE"
    break
  fi

  echo "Rate limited. Retrying in ${DELAY}s..."
  sleep $DELAY
  DELAY=$((DELAY * 2))
done

Майбутні зміни

Планується впровадження персистентного rate limiting на базі Redis. Це забезпечить збереження лімітів після перезапуску сервера та їх послідовне застосування на кількох екземплярах сервера. Стандартний ліміт у 60 запитів на хвилину залишиться незмінним.