Rate Limiting

Qamera AI API wymusza limity zapytań (rate limiting), aby zapewnić sprawiedliwe użytkowanie i stabilność platformy. Limity są stosowane per API key.

Domyślne limity

Każdy API key może wykonać do 60 zapytań na minutę. Limit ten obowiązuje dla wszystkich endpointów — zarówno zapytania GET, jak i POST są wliczane do tego samego limitu.

Implementacja

Rate limiting wykorzystuje licznik oparty na przesuwnym oknie w pamięci (in-memory sliding window). Okno śledzi zapytania z ostatnich 60 sekund i odrzuca nowe zapytania po przekroczeniu limitu.

Ponieważ licznik jest przechowywany w pamięci, resetuje się przy restarcie serwera API. Nie polegaj na tym zachowaniu — przyszłe wersje będą wykorzystywać trwały rate limiting oparty na Redis.

Odpowiedź 429

Po przekroczeniu limitu API zwraca odpowiedź 429 Too Many Requests:

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

Strategie ponawiania

Exponential Backoff (zalecany)

Gdy otrzymasz odpowiedź 429, odczekaj przed ponowieniem. Zwiększaj opóźnienie z każdą kolejną próbą:

Próba 1: odczekaj 1 sekundę
Próba 2: odczekaj 2 sekundy
Próba 3: odczekaj 4 sekundy
Próba 4: odczekaj 8 sekund

Dodaj niewielki losowy jitter (0–500 ms) do każdego opóźnienia, aby uniknąć zsynchronizowanych ponowień z wielu klientów.

Proste opóźnienie

Dla prostszych implementacji odczekaj stałe 2 sekundy po każdej odpowiedzi 429 przed ponowieniem.

Rozkładanie zapytań

Jeśli Twoje obciążenie obejmuje serie zapytań, rozłóż je równomiernie w oknie minutowym. Przy 60 zapytaniach na minutę celuj w mniej więcej jedno zapytanie na sekundę.

Przykład: Ponowienie z backoff

#!/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://app.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

Planowane zmiany

Planowany jest trwały rate limiting oparty na Redis. Zapewni on zachowanie limitów po restartach serwera i spójne egzekwowanie na wielu instancjach serwerowych. Domyślny limit 60 zapytań na minutę pozostanie bez zmian.