Rate limiting

Limity sú per-API-kľúč a per-minúta. Implementácia je sliding window v Redise – počíta posledných 60 sekúnd, nie kalendárnu minútu, takže nezáleží kedy presne začneš.

Limity podľa plánu

Limit reaguje okamžite na zmenu plánu – po upgrade na Pro nemusíš nič rotovať. Per-tier hodnota sa cachuje 5 minút (300 s), takže po upgrade plánu môže nový limit dotiahnuť až do tejto doby.

Rate-limit hlavičky

Každá odpoveď obsahuje 3 hlavičky:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 873
X-RateLimit-Reset: 1717689600

• • X-RateLimit-Limit – maximum povolených requestov za 60 sekúnd
• • X-RateLimit-Remaining – koľko ti ich ešte zostáva
• • X-RateLimit-Reset – Unix timestamp (sekundy) kedy sa najstarší request v okne uvoľní

Prekročenie limitu

Po prekročení dostaneš HTTP 429 Too Many Requests:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 14
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1717689614

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Try again in 14 seconds."
  }
}

Hlavička Retry-After ti povie koľko sekúnd treba počkať. Klient by mal mať exponential backoff + rešpektovať Retry-After.

Quota (mesačná kvóta)

Niektoré operácie navyše čerpajú mesačnú kvótu plánu (napr. počet odoslaných emailov, počet AI extrakcií). Po prekročení dostaneš 402 Payment Required s kódom QUOTA_REACHED:

{
  "error": {
    "code": "QUOTA_REACHED",
    "message": "Plan limit reached for ai_scans (10/10 used)."
  }
}

QUOTA_REACHED je oddelená od 429 (rate limit) – upgrade plánu zruší kvótu okamžite. Pozri plány.

Best practices

• • Caching – read-only dáta (kategórie, série) cachuj na klientovi minimálne 5 min.
• • Stránkuj rozumne –limit=100 je lepšie než 100× limit=1.
• • Backoff – pri 429 čakaj Retry-After sekúnd, nie hneď retry.
• • Jeden kľúč na integráciu – uľahčí to debug + revokovanie keď niečo praskne.